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Notices 

The information contained in this document is subject to change without notice. 

Hewlett-Packard provides the following material “as is” and makes no warranty 
of any kind with regard to this manual, including, but not limited to, the implied 
warranties of merchantability and fitness for a particular purpose. Hewlett- 
Packard shall not be liable for errors contained herein or direct, indirect, special, 
incidental or conseguential damages (including lost profits) in connection with 
the furnishing, performance, or use of this material whether based on warranty, 
contract, or other legal theory. 

Some states do not allow the exclusion of implied warranties or the limitation 
or exclusion of liability for incidental or consequential damages, so the above 
limitation and exclusions may not apply to you. This warranty gives you specihc 
legal rights, and you may also have other rights which vary from state to state. 

Hewlett-Packard assumes no responsibility for the use or reliability of its software 
on equipment that is not furnished by Hewlett-Packard. 

Warranty. A copy of the specihc warranty terms applicable to your Hewlett- 
Packard product and replacement parts can be obtained from your local Sales 
and Service Office. 


Copyright © 1997 Hewlett-Packard Company This document contains informa¬ 
tion which is protected by copyright. All rights are reserved. Reproduction, 
adaptation, or translation without prior written permission is prohibited, except 
as allowed under the copyright laws. 

Restricted Rights Legend. Use, duplication or disclosure by the U.S. Government 
is subject to restrictions as set forth in subparagraph (c)(l)(ii) of the Rights in 
Technical Data and Computer Software clause in DFARS 252.227-7013. Rights 
for non-DoD U.S. Government Departments and Agencies are as set forth in 
FAR 52.227-19(c)(l,2). 

Use of this manual and hexible disc(s), or tape cartridge(s), or CD-ROM supplied 
for this pack is restricted to this product only. Additional copies of the programs 
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can be made for security and back-up purposes only. Resale of the programs in 
their present form or with alterations, is expressly prohibited. 

PEX and PEXlib are trademarks of Massachusetts Institute of Technology. 
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Printing History 

New editions of this manual will incorporate all material updated since the 
previous edition. Update packages may be issued between editions and contain 
replacement and additional pages to be merged into the manual by the user. 
Each updated page will be indicated by a revision date at the bottom of the 
page. A vertical bar in the margin indicates the changes on each page. Note that 
pages which are rearranged due to changes on a previous page are not considered 
revised. 

The manual printing date and part number indicate its current edition. The 
printing date changes when a new edition is printed. (Minor corrections and 
updates which are incorporated at reprint do not cause the date to change.) The 
manual part number changes when extensive technical changes are incorporated. 

July 1997 ... Edition 1. This manual is valid for the July 1997 Workstation ACE 
for HP-UX 10.20 on all HP 9000 workstations and servers. 
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Chapter 0: Preface 


Why This Document? 

This document (whose browsable version is accessible by using your browser’s 
“File^Open File” on /opt/graphics/common/doc/GAG/Web/index.html) was 
created to hll a need that became evident as Hewlett-Packard began to offer 
multiple Application Programmer Interfaces (APIs). The situation was this: As 
HP created one API—say, Starbase—particular aspects of graphical operation 
were noted and diligently explained in the Starbase documentation. However, 
some of these aspects were not unique to Starbase, they pertained to graphics 
operation in general: they applied to all of our APIs. Therefore, those users who 
had HP-PHIGS would be encountering some of the same graphical questions that 
were already well-documented in the Starbase documentation. But HP-PHIGS 
users wouldn’t necessarily have the Starbase documentation. Are they just out 
of luck? The same situation occurred with HP PEX. 

Our dilemma was this: do we copy the general-graphics explanations that 
already existed in the Starbase documentation, into the documentation for the 
other APIs as well? This would mean two, three, or even more virtually 
identical copies of the same explanations in different places, requiring similar 
changes in each whenever new capabilities or devices were introduced. And 
if all documents containing these similar explanations were not reprinted 
simultaneously, “current” documents for the various APIs might contradict each 
other. 

A more elegant solution is: this document. While the API-specihc documents 
still contain most of their previous contents, the general graphical information— 
common to all APIs—was moved here. Examples include: 

■ Pathnames: File locations have changed between HP-UX 9.x and HP-UX 10.a;, 
with its new, standardized V.4 hie system structure. 
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■ Creating device files: Regardless of whether it is Starbase, HP-PHIGS, or HP 
PEX that creates an image, you have to tell the operating system where the 
display is and how to talk to it. 

■ Compiling and Linking: The process of turning your source code into executable 
code has many common ideas, regardless of API or file system structure. 

■ X Windows issnes: All APIs interact with X windows, so non-unique X 
Windows information comes here. 

The above topics, and others as well, are good candidates for a common area. 
With this approach, only one copy of the common information need exist, and 
revisions can happen in a more timely manner, and at less risk of contradicting 
other documents. 


Document Conventions 


Below is a list of the typographical conventions used in this document: 


mknod /usr/include Verbatim computer literals are in computer font. 

Text in this style is letter-for-letter verbatim and, 
depending on the context, should be typed in exactly 
as specified, or is named exactly as specified. 

In every case ... Emphasized words are in italic type. 


... device is a freen ... New terms being introduced are in bold-faced type. 

... the {device_id) ... Conceptual values are in italic type, enclosed in angle 

brackets. These items are not verbatim values, but are 
descriptors of the type of item it is, and the user should 
replace the conceptual item with whatever value is 
appropriate for the context. 
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Pathnames 



This chapter contains information on locating hies that reside at some location— 
currently unknown to you—in the hie system. This is important, because you 
may have an “old” hie system (on HP-UX 9.x and earlier) or a “new” V.4 hie 
system (on HP-UX 10.a; and later). Most hies in the old hie system still exist in 
the new, but they may reside in different locations. This can cause inconvenience 
if the new location of a hie is unknown to you. This chapter addresses the task 
of hnding hies, regardless of your hie system. 


Using “whence” 

There are two main methods of hnding hies, assuming you know the name of 
the hie you’re looking for. The hrst method is to use the Korn-shell command 
whence, which tells you where commands reside (if you’re not using the Korn 
shell, you can use the system command whereis): 

$ whence mknod [Return ] 

/etc/mknod 

The above approach, while satisfactory in many cases, has two limitations: 

■ First, the directory in which the command resides must be one of the entries 
in the PATH variable; if it is not, it won’t be found. So in a sense, whence and 
whereis can only hud things if you tell them where to look. They are still 
valuable, though: you may not remember which, of the dozens of directories 
that may be in your PATH variable, is where a particular command resides. Also, 
if you have two commands of the same name in two different directories, whence 
and whereis will tell you which one will be found hrst, and thus executed. 

■ Secondly, both whence and whereis only hud executable hies; that is, 
commands (both compiled programs and shell scripts). If you want to hud a 
hie that is not executable—an include hie, for instance—whence and whereis 
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will not find it, even if the include file’s directory is in your PATH. To find non¬ 
executable files, you can use find, discussed below. 


Using “find” 

The find command will find any file in your file system, executable or not. For 
example, to locate the include file we couldn’t locate above, you could say: 

$ find / -name {file_name) [Return ") 

where {file_name ) is the name of the file you’re looking for. In the above example, 
the “/” is the root directory, and everything is under that, so—assuming you 
specified the correct file name, and it is somewhere in the file system—the above 
command is guaranteed to find what you’re looking for, though it make take a 
while. You can shorten the search time by giving a subdirectory here, if you know 
it; for example, “find /opt ... ”. Also, you can specify just a partial filename; 
find will locate all files containing a specified substring in their names. The find 
command has many other options for refining a search; see the reference page for 
details. 

Subsequent sections of this chapter contain the actual pathnames referred to in 
other HP graphics API documents, such as Starbase, PEX, etc. A particular 
paragraph might refer to, say, the [demos) directory. That directory on an 9.a; 
system may be in a different location than on a 10.a; system, so the sections below 
allow you to resolve the actual path name, given the HP-UX operating system 
version you have, and the API you are working with. 

Find the API you’re looking for, then under that, the operating system you have 
(the old 9.a; or the new 10.a; file system). In that section is an alphabetical list of 
“generic names”—the file system path references used in the other documents— 
and with each, you will see its actual location in the file system. 
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Starbase, HP-UX 9.x File System 
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(common) 

(didn’t exist in 9.2; file system) 

(dev) 

/dev 

(formatters) 

/usr/lib/starbase/formatters 

(m/s) 

/usr/lib/nls 

(sb-demos) 

/usr/lib/starbase/demo 

(sb-fonts) 

/usr/lib/starbase/stroke 

(sb-font-mfo) 

/usr/lib/starbase/stroke/font_info 

(sb-mcl) 

/usr/include 

(sb-Ub) 

/usr/lib 

(sb-utils) 

/usr/lib/starbase/demos/SBUTILS 

(screen) 

/dev/screen 

(starbase) 

/usr/lib/starbase 

(tmp) 

/tmp 

(vue-config) 

/usr/vue/config 

(xll) 

/usr/lib/Xll 

(xll-admin) 

/usr/lib 

(xllr5) 

/usr/lib/XllR5 

(xllr5-incl) 

/usr/include/XllR5 

(xconfig) 

/usr/lib/Xll 
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Starbase, HP-UX 10.x File System 

Note that before HP-UX 10.20, the default release number of the X window 
system was X11R5; as of HP-UX 10.20, it is X11R6. If your version of HP-UX 
is 10.20 or newer, the occurrences of X11R5 in the pathnames below should be 
understood as X11R6. 


(common) 

/ opt/graph!c s/common 

(dev) 

/dev 

(formatters) 

/opt/graph!c s/starbase/f ormatt ers 

(nls) 

/opt/graph!cs/common/l!b/nls/msg/C 

(sb-demos) 

/opt/graph!cs/starbase/demo 

(sb-font) 

/opt/graph!cs/common/stroke 

(sb-font-mfo) 

/opt/graph!cs/common/stroke/font_!nfo 

(sb-mcl) 

/opt/graph!cs/starbase/!nclude 

(sb-Ub) 

/opt/graph!c s/common/1!b 

(sb-utils) 

/opt/graph!cs/starbase/demos/starbase/SBUTILS 

(screen) 

/dev/screen 

(starbase) 

/opt/graph!c s/starbas e 

(tmp) 

/var/tmp 

(vue-config) 

/etc/vue/conf!g 

(xll) 

/usr/l!b/Xll 

(xll-admin) 

/etc/Xll 

(xllr5) 

/usr/l!b/XllR5 

(xllr5-incl) 

/usr/!nclude/XllR5 

(xconfig) 

/etc/Xll 
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HP-PHIGS, HP-UX 9.x File System 
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[app-defaults) 

/usr/lib/Xll/app-defaults 

(common) 

(didn’t exist in 9.2; file system) 

(dev) 

/dev 

(nls) 

/usr/lib/nls 

(phtgs) 

/usr/lib/phigs 

(phigs-demos) 

/usr/lib/phigs/demos 

(phtgs-examples) 

/usr/lib/phigs/examples 

(phtgs-tncl) 

/usr/include 

(phtgs-Uh) 

/usr/lib 

(phigs-widget) 

/usr/include/Motif1.2 

(screen) 

/dev/screen 

(spool) 

/usr/spool 

(siarbase) 

/usr/lib/starbase 

(vue-config) 

/usr/vue/config 

(xll) 

/usr/lib/Xll 

(xllr5) 

/usr/lib/XllR5 

(xllr5-incl) 

/usr/include/XllR5 

(xconfig) 

/usr/lib/Xll 
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HP-PHIGS, HP-UX 10.x File System 

Note that before HP-UX 10.20, the default release number of the X window 
system was X11R5; as of HP-UX 10.20, it is X11R6. If your version of HP-UX 
is 10.20 or newer, the occurrences of X11R5 in the pathnames below should be 
understood as X11R6. 


[app-defaults) 

/usr/lib/Xll/app-defaults 

(common) 

/opt/graph!c s/common 

(dev) 

/dev 

(nls) 

/opt/graphics/common/lib/nls/msg/C 

(phtgs) 

/opt/graphics/phigs 

(phigs-demos) 

/opt/graphics/phigs/demos 

(phtgs-examples) 

/opt/graphics/phigs/examples 

(phtgs-tncl) 

/opt/graphics/phigs/include 

(phtgs-Uh) 

/opt/graphics/phigs/lib 

(phigs-widget) 

/opt/graphics/phigs/include/Motif1.2 

(screen) 

/dev/screen 

(spool) 

/var/spool 

(siarbase) 

/opt/graph!c s/st arbas e 

(vue-config) 

/etc/vue/config 

(xll) 

/usr/lib/Xll 

(xllr5) 

/usr/lib/XllR5 

(xllr5-incl) 

/usr/include/XllR5 

(xconfig) 

/etc/Xll 
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HP PEX, HP-UX 9.x File System 


1 



[app-defaults) 

/usr/lib/Xll/app-defaults 

[eg e-examples) 

/usr/lib/PEX5/cge_examples 

[ege-utils) 

/usr/lib/PEX5/cge_utilities 

[eoninb) 

/usr/contrib 

[err-help) 

/usr/lib/PEX5 

[extensions) 

/usr/lib/Xll/extensions 

[hp-examples) 

/usr/lib/PEX5/hp_examples 

[man) 

/usr/man 

[nls) 

/usr/lib/nls 

[ora-examples) 

/usr/lib/PEX5/ora_examples 

[pex) 

/usr/lib/PEX5 

[pexd) 

/usr/bin/Xll 

[pex-examples) 

/usr/lib/PEX5/examples 

[pex-fonts) 

/usr/lib/PEX5/fonts 

[pex-inel) 

/usr/include 

[pex-lib) 

/usr/lib 

[pex-utils) 

/usr/lib/PEX5/utilities 

[profile) 

/usr/contrib/PEX5/lib 

[rel-notes) 

/etc/newconfig 

[spool) 

/usr/spool 

[vhelp) 

/usr/vhelp 

[vue) 

/usr/vue 

[xll) 

/usr/lib/Xll 

[xll-mel) 

/usr/include/Xll 

[xllr5) 

/usr/lib/XllR5 

[xllr5-inel) 

/usr/include/XllR5 
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HP PEX, HP-UX 10.x File System 

Note that before HP-UX 10.20, the default release number of the X window 
system was X11R5; as of HP-UX 10.20, it is X11R6. If your version of HP-UX 
is 10.20 or newer, the occurrences of X11R5 in the pathnames below should be 
understood as X11R6. 


[app-defaults) 

/usr/lib/Xll/app-defaults 

[eg e-examples) 

/opt/graphics/PEX5/examples/ege 

[ege-utils) 

/opt/graphics/PEX5/utilities/ege 

[eoninb) 

/opt/graphics/PEX5/contrib 

[err-help) 

/opt/graphics/PEX5/help5.1 

[extensions) 

/opt/graphics/PEX5/newconfig/usr/lib/Xll/extensions 

[hp-examples) 

/opt/graphics/PEX5/examples/hp 

[man) 

/opt/graphics/PEX5/share/man 

[nls) 

/opt/graphics/PEX5/lib/nls/msg/C 

[ora-examples) 

/opt/graphics/PEX5/examples/OReilly 

[pex) 

/opt/graphics/PEX5 

[pexd) 

/opt/graphics/PEX5/lbin 

[pex-examples) 

/opt/graphics/PEX5/examples 

[pex-fonts) 

/opt/graphics/PEX5/fonts 

[pex-inel) 

/opt/graphics/PEX5/include/XllR5/Xll/PEX5 

[pex-lib) 

/opt/graphics/PEX5/lib 

[pex-utils) 

/opt/graphics/PEX5/utilities 

[profile) 

/opt/graphics/PEX5/contrib 

[rel-notes) 

/opt/graphics/PEX5/newconfig/opt/graphics/PEX5 

[spool) 

/var/spool 

[vhelp) 

/opt/graphics/PEX5/help5.1 

[vue) 

/usr/vue 

[xll) 

/opt/graphics/PEX5/newconfig/usr/lib/Xll 

[xll-mel) 

/usr/include/XllR5/Xll 

[xllr5) 

/opt/graphics/PEX5/lib/XllR5 

[xllr5-inel) 

/usr/include/XllR5 


1-8 Pathnames 


FINAL TRIM SIZE : 7.5 in x 9.0 in 




Compiling Your Application 


This chapter provides information for compiling you application with either 
archived or shared libraries for the following Application Programming Interfaces 
(APIs): Starbase, HP-PHIGS, and HP PEX. Compiling examples are given for 
C, Fortran, and Pascal. 

The actual pathnames of the conceptual (italicized and angle-bracketed) directory 
names in this chapter depends on the hie system structure, which differs between 
HP-UX 9.x and HP-UX 10.a;. See Chapter 1 for details. 
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Compiling Starbase Applications 


Compiling with Shared Libraries 

The compiler programs (cc, f77, and pc) link with Starbase shared li¬ 
braries by default. Starbase will explicitly load the appropriate device driver 
library at run time when you compile and link with the shared library 
(common)/lib/libhpgfx. si, or use the -Ihpgfx option. This loading occurs at 
gopen(3G) time. 

Examples 

Assuming you are using ksh(l), to compile and link a C program for use with 
the shared library driver, use the forms below. 

cc example.c -l{sh-incl) -L{common) -L{sh-lib) -IXwindow \ 

-Ihpgfx -IXhpll -1X11 -Im -o example 

For FORTRAN: 

fort77 example.! -l{sh-incl) -L{common) -L{sh-lih) -IXwindow \ 
-Ihpgfx -IXhpll -1X11 -Im -o example 

For Pascal: 

pc example.p -l{sh-incl) -W1,-L(common) -VI,-L {sb-Ub) \ 

-IXwindow -Ihpgfx -IXhpll -1X11 -Im -o example 

Compiling with Archive Libraries 

You can link the appropriate library, for your specihc device driver, to a program 
by using any one of the following: 

■ The path name {sb-Ub)/{library_name) .a] 

■ An appropriate relative path name; or 

■ The -ldd{device_drwer) option (for example, -Iddhcrx) with the LDOPTS 
environment variable set to -a archive and exported. Or (preferred because 
of fewer side-effects), “-W1, -a,archive”. 

By default, the linker program ld(l) looks for a shared library driver hrst and 
then the archive library driver if a shared library was not found. By using “- 
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W1,-a,archive” (or exporting the LDOPTS variable), the -1 option will refer only 
to archive drivers. 

As of HP-UX 9.05, archive libraries utilize functionality that is included in 
libXext.a. Because the archive library libhpgfxl.a references functionality 
in libXext.a, it is necessary to explicitly link libXext.a with your program. 
Otherwise, the linker will have undehned references. 

Examples 

Assuming you are using ksh(l), to compile and link a C program for use with 
this driver, use the forms below. 

The “-Irlibdld.sl” below specihes the dynamic loader, which is available only 
in shared-library form. 

cc example.c -l{sh-incl) -W1,-a,archive -L{common) -L{sh-lih) \ 
-ldd{device_drwer) -IXwindow -Ihpgfxl -lhpgfx2 -IXhpll \ 

-IXext -1X11 -Wl,-E -Wl,+n -Irlibdld.sl -Im -o example 

For FORTRAN, use: 

fort77 example.! -l{ sh-incl) -W1,-a,archive -L{common) \ 
-L{sh-lih)-ldd{device_drwer) -IXwindow -Ihpgfxl -lhpgfx2 \ 

-IXhpll -IXext -1X11 -Wl,-E -Wl,+n -Irlibdld.sl -Ime \ 

-o example 

For Pascal, use: 

pc example.p -l{sh-incl) -W1,-a,archive -W1,-L(common) \ 

-VI ,-L{sb-Ub) -Idd {device_drwer) -IXwindow -Ihpgfxl \ 

-lhpgfx2 -IXhpll -IXext -1X11 -Wl,-E -Wl,+n \ 

-l:libdld.sl -Im -o example 
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Compiling HP-PHIGS Applications 


Compiling with Shared Libraries 

If you are using shared libraries, as we recommend, linking is device-independent. 
To compile a C program using shared libraries, you would use the following 
command: 

cc example.c -l{phigs-incl) -L{common)/lih -L {phigs-lih) \ 
-l{phigs-widget)/Hotifl .2 -IXwindow -Iphigs -Idl \ 

-Ihpgfx -Idld -IXhpll -IXi -IXext -1X11 -Im -o example 

FORTRAN users can simply replace cc with fort77 in the above command. 
Also, if you are a FORTRAN user and prefer using the f77 command, you can 
replace cc with f77 and change linking options that are specihed as follows: 

-L{pathname) 

to 

-W1, -L{pathname) 

For more information on compiling and linking, read the section “PHIGS PLUS 
Differences Between HP-PHIGS 2.2/2.3 and 3.0” in the chapter “Functional 
Overview” in the HP-PHIGS Graphics Technigues manual. 

Compiling with Archive Libraries 

If you are using archived libraries, you need to include your device’s driver library. 
Note that shared libraries are used by default unless you specify that you want 
to use archived libraries (by specifying “-W1,-a,archive”). 

To compile a C program using archived libraries, you would use the following 
command: 

cc example.c -l{phigs-incl) -W1,-a,archive -L(common)/lib \ 
-L{phigs-lib) -l{phigs-widget)/Hotifl .2 -ldddl{device_drwers) \ 

-Wl,-E -Wl,+n -l:libdld.sl -IXwindow -Iphigs -Idl \ 

-Ihpgfxl -lhpgfx2 -IXhpll -IXi -IXext -1X11 -Im \ 

-o example 

The “-l:libdld.sl” above specihes the dynamic loader, which is available only 
in shared-library form. 
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Multiple graphics device driver libraries may be indicated in the [device^drivers) 
location. For example, if your application source hie is called app_one.c and 
the executable is app_one and you are using the CRX graphics device driver 
(libddgcrx), your compile command would look like this: 

cc app_one.c -Wl,-a,archive -L(common)/lib \ 

-L{phigs-lih) -l[phigs-widget) /Motif 1.2 -Idddl -Iddgcrx \ 

-Wl,-E -Wl,+n -Irlibdld.sl -IXwindow -Iphigs -Idl \ 

-Ihpgfxl -lhpgfx2 -IXhpll -IXi -IXext -1X11 -Im \ 

-o app_one 

The “-Irlibdld.sl” above specihes the dynamic loader, which is available only 
in shared-library form. 

Fortran users can simply replace cc with fort77 in the above command. Also, 
if you are a Fortran user and prefer using the f 77 command, you can replace cc 
with f77 and change linking options that are specihed as follows: 

-L{pathname) 

to 

-W1, -L{pathname) 

For more information on compiling and linking, read the section “PHIGS PLUS 
Differences Between HP-PHIGS 2.2/2.3 and 3.0” in the chapter “Functional 
Overview” in the HP-PHIGS Graphics Technigues manual. 
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Device Driver Libraries 


2 


The following tables list the device driver libraries that should be used with 
particular devices. 


Table 2-1. CRX Family 


Output Device 

Link Line Options 

Integrated Color Graphics 

libddgcrx.a 

(Model 705, 710, 

715/33, 715/50, 715/75, 

725/50, 725/75) 

or 

libddgcrx.si 

Internal Color Graphics 


(Model 712/60, 712/80, 

712/80i, 712/100, 

715/64, 715/80, 715/100, 
715/lOOXC, 

725/100) 


HP CRX/GRX 

HP Dual CRX 

HP CRX-24[Z] 


HP CRX-48Z 

libddcrx48z.a 

or 

libddcrx48z.si 


Table 2-2. HCRX and HP Visualize Families 


Output Device 

Link Line Options 

HP Visualize-EG 

HP HCRX-8[Z] 

HP HCRX-24[Z] 

HP Visualize-8 

HP Visualize-24 

libddhcrx.a 

or 

libddhcrx.si 

HP Visualize-48[XP] 

libddhcrx48.a 

or 

libddhcrx48.si 
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Table 2-3. HP Visualize-FX Family 


Output Device 

Link Line Options 

Legacy APIs 

HP Visualize-EG 

libddhcrx.a 

or 

libddhcrx.si 

HP Visualize-FX^ 

HP Visualize-FX"‘ 

HP Visualize-FX® 

libddvisx.a 

or 

libddvisx.si 

OpenGL 

HP Visualize-EG 

libddhcrx.a 

or 

libddhcrx.si 

HP Visualize-FX^ 

HP Visualize-FX"‘ 

HP Visualize-FX® 

libddvisxgl.si 
libddvmd.si 



Table 2-4. VRX Family 


Output Device 

Link Line Options 

Personal VRX (P3) 

libdd98704.a, 

libdd98705.a, 

libdd98704.sl, 

or 

libdd98705.sl 

Turbo VRX (T2/T4) 

libdd98765.a, 

libdd98766.a, 

libdd98765.sl, 

or 

libdd98766.sl 
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Table 2-5. HP-GL Plotters 


Output Device 

Link Line Options 

HP 7440A 

libddhpgl.a libdvio.a 

HP 7470A 

or 

HP 7475A 

libddhpgl.sl libdvio.sl 

HP 7550A 


HP 7570A 


HP 7575A 


HP 7576A 


HP 7580A/B 


HP 7585B 


HP 7586B 


HP 7595A 


HP 7596A 


HP 9111A 


HP C1600A 


HP C1601A 


HP 7510A 

libddCADplt.a 

HP 7550A 

or 

HP 7570A 

libddCADplt.si 

HP 7575A 


HP 7576A 


HP 7580B1 


HP 7585B1 


HP 7586B 


HP 7595A/B 


HP 7596A/B 


HP 7599A 


HP C1600A 


HP C1601A 


HP C1602A1 


HP C1620A 


HP C1625A 


HP C1627A 


HP C1629A 


HP C1631A 


^ With HP-GL/2 plug-in cartridge 
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Table 2-6. Miscellaneous Device Drivers 


Output Device 

Link Line Options 

Remote Rendering: 

Xlib Pixmap (VMX) 

libddvmx.sl^ 

Remote Rendering: 

Xlib 2D protocol (SOX) 

libddsoxll. a 

or 

libddsoxll. si 

Display List 

libdddl.a 

or 

libdddl.si 

Computer Graphics Metafile 
(CGM) File Format 

libddhpcgm.a 

or 

libddhpcgm.si 

Starbase Memory Driver 
(pixel-major packing orders) 

libddSMDpix.a 

or 

libddSMDpix.si 

Starbase Memory Driver 
(plane-major packing order) 

libddSMDpln.a 

or 

libddSMDpln.sl 

The Personal Visualizer 

File Format 

libddhpsbv.a 

or 

libddhpsbv.si 

^ The “.a” version of the VMX driver is bundled with the hpgfx 
library. 
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Compiling HP PEX Applications 

HP PEXlib is supported on the Series 700 workstations using shared libraries 
that must be linked with the application program. Only PEX programs written 
in C (not EORTRAN or Pascal) are supported. 

When you compile your PEXlib programs, you must link the application with the 
PEXlib library libPEXS. Note that the PEX library is dependent on the math 
library. 

A compile line will typically appear: 

cc program.c -1PEX5 -IXext -1X11 -Im 

Eor more information on compiling and linking PEXlib programs, see the appro¬ 
priate chapters in the HP PEX Implementation and Programming Supplement. 
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Compiling OpenGL Applications 

HP’s implementation of OpenGL is supported on workstations with 
HP Visualize-FX graphics. 

To compile a program that does not use the OpenGL utilities, use a makehle 
that looks like this: 

INCDIR= -I/opt/graphics/OpenGL/include -I/usr/include/XllR5 
LIBDIR=-L/opt/graphics/OpenGL/lib -L/usr/lib/XllR5 
LIBS=-1GL -IXext -1X11 -Im -Idld 



meow : meow.c 

cc KlNCDIR) KLIBDIR) -o meow meow.c $(LIBS) 

To compile a program that does use the OpenGL utilities, use a makehle that 
looks like this: 

INCDIR= -I/opt/graphics/OpenGL/include -I/usr/include/XllR5 
LIBDIR=-L/opt/graphics/OpenGL/lib -L/usr/lib/XllR5 
LIBS=-1GLU -IGL -IXext -1X11 -Im -Idld 


meow : meow.c 

cc KlNCDIR) KLIBDIR) -o meow meow.c KLIBS) 
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X Windows, HP-UX 9.0x 


This chapter documents information specihc to the HP X server on HP-UX 9.0a;. 
It describes features unique to HP’s X server, provides information on how to 
conhgure the X server and includes a list of supported X conhgurations. For 
each supported graphics device, device-dependent conhguration information is 
provided. 

Information specihc to a new release of the X server, beyond the scope of the 
general information in this document, can be found in the HP-UX release notes 
located in /etc/newconf ig. 

If you prefer to see this information in an ASCII hie, please refer to the hie 
/usr/lib/Xll/Xserver/info/screens/hp. It includes the same information as 
is contained in this chapter. 
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The X*screeiis File 


The X*screens file is used to configure the operation of the X server. Please refer 
to the sample file in /usr/lib/Xll/XOscreens, for more information on how to 
use the X*screens file. 


Miscellaneous Topics 

Setting/Unsetting Environment Variables 

Each type of shell (sh, csh and ksh) have dilferent ways of setting and unsetting 
the value of environment variables to desired values. The following table shows 
an example of how the DISPLAY variable is set (where [value) would be in the 
[host)'.[display) .[screen ) format) and unset for each shell type. 


Table 3-1. Setting and Unsetting Environment Variables 


Shell 

Setting the Variable 

Unsetting the Variable 

sh 

DISPLAY=(ra/Me) 
export DISPLAY 

unset DISPLAY 

ksh 

export DISPLAY=(ra/Me) 

unset DISPLAY 

csh 

setenv DISPLAY [value) 

unsetenv DISPLAY 


Throughout this file, when an environment variable is defined, it will include 
a list of valid values or will state that any value is acceptable. When any 
value is specified, any non-null string is acceptable, but often the value is set 
by convention, to TRUE (e.g., “export [variable) =TRUE” in ksh). 

Double Buffer Extension (DBE) 

DBE is an extension to the X server that provides a double-bulfering Application 
Programming Interface (API). Note that MBX (the Multi-Buffering extension 
to X) has not been adopted as an industry standard, as DBE has. Thus, it 
is recommended that applications that use MBX be ported to DBE usage in 
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preparation for future MBX obsolescence. For more information about DBF and 
the API, consult the DBF man pages: 

■ DBF 

■ XdbeQueryExtension 

■ XdbeGetVisualInfo 

■ XdbeFreeVisualInfo 

■ XdbeAllocateBackBufferName 

■ XdbeDeallocateBackBufferName 

■ XdbeSwapBuffers 

■ XdbeBeginIdiom 

■ XdbeEndIdiom 

■ XdbeGetBackBufferAttributes 

Performing Buffer Swaps on Vertical Blank 

For performance reasons, the default DBF behavior is to not synchronize buffer 
swaps with the monitor’s vertical retrace period. In some instances, therefore, 
image tearing (seeing part of the old image and part of the new image on the 
display at the same time) could be visible while swapping large DBF windows. 
For those instances where tearing would occur and is undesirable, an optional X 
server mode is available to allow for synchronization of buffer swaps with vertical 
retrace. To activate this optional X server mode, set the environment variable 
SWAP_BUFFERS_ON_VBLANK to any value before the X server is started. 

Supported Devices 

The X server supports DBF on the following devices: 

■ Internal Color Graphics 

■ Integrated Color Graphics 

■ Color Graphics cards 

■ Dual Color Graphics cards 

■ CRX 

■ CRX-24[Z] 

■ CRX-48Z 

■ HCRX-8[Z] 

■ HCRX-24[Z] 

■ HP Visualize-8 

■ HP Visualize-24 
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■ HP Visualize-48 

■ Freedom Series™ Graphics (S3150, S3250 and S3400) (“Freedom Series” is a 
trademark of Evans & Sutherland Computer Corporation.) 

MBX 

The MBX extension (Multi-Buffering Extension) is supported on all graphics 
devices supported on the HP 9000/700 machines, except the PersonalVRX and 
the TurboVRX. 

HP’s implementation of MBX exists mainly to support fast double-buffering for 
PEX applications. Therefore, MBX only supports allocation of one or two MBX 
buffers; no more. Some graphics devices/visuals have a single 8-plane buffer; 
these include Internal Color Graphics, Integrated Color Graphics, Color Graphics 
cards. Dual Color Graphics cards and the overlay planes on the CRX-24[Z], 
CRX-48Z, the HCRX family and the Freedom Series Graphics (S3150, S3250 
and S3400). For these devices, MBX double-buffering is still supported, but the 
second bank is allocated in virtual memory. Rendering and buffer-swapping in 
these instances is slower than devices/visuals that support true hardware double¬ 
buffering. 

Currently, there is no easy way to determine which visuals, from a device’s list of 
visuals, support fast MBX hardware double-buffering. The CRX and Dual-CRX 
device is a double-buffered device and therefore always supports MBX hardware 
double-buffering. The Internal Color Graphics, Integrated Color Graphics, Color 
Graphics cards and Dual Color Graphics cards only support MBX software 
buffering. All other devices that have both overlay and image planes support fast 
MBX hardware double-buffering in the image planes and slower MBX software 
double-buffering in the overlays. Consult the following device-specihc sections 
for a list of visuals that support software and hardware MBX double-buffering. 

For performance reasons, the default MBX behavior is to not synchronize with 
the monitors vertical retrace period. In some instances, image tearing could be 
visible while swapping large MBX windows. For those instances where tearing 
would occur and is undesirable, an optional X server mode is available to allow for 
synchronization with vertical retrace. To activate this optional X server mode, 
set the environment variable SWAP_BUFFERS_0I_VBLAIK to any value before the 
X server is started. 
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With this mode enabled, all MBX buffer swaps are synchronized with the 
monitor’s vertical retrace period. This mode is not needed in drawables used 
for PEX rendering. PEX turns synchronization on and thus does not require this 
tuning. 

The MBX Application Programming Interface is thoroughly discussed in the 
O’Reilly & Associates, Inc. PEXlib Programming Manual by Tom Gaskins. 
Consult that manual to understand the creation, manipulation, and destruction 
of MBX buffers. 

Since MBX is not an industry standard, developers should replace MBX calls 
with DBE calls. 


Note 



Note that XmbufGetScreenInfoO can indicate that a window 
supports MBX even if only one MBX buffer is supported. An 
application should always check the max_buffers held in the 
returned XmbufBufferinfo structure before assuming that a 
window supports two MBX buffers. 


Single Logical Screen (SLS) 

SLS is a mechanism for treating homogeneous multi-display conhgurations as 
a single “logical” screen. This allows the moving/spanning of windows across 
multiple physical screens. “Homogeneous” means SLS only works if the graphics 
devices included in the “SLS Conhguration” are of the same type (see the list 
of the supported SLS conhgurations shown below.) SLS is enabled via the 
/usr/lib/Xll/XOscreens hie with the syntax: 

SingleLogicalScreen n m 

/dev/crtO ... /dev/crtfc 

where n=the number of “rows” in the physical conhguration, m=the number of 
“columns” in the physical conhguration, and the product of nxm is less than or 
equal to four. 

Eor example, to create a logical screen that is one screen tall by two screens wide, 
the following syntax would be used: 

SingleLogicalScreen 1 2 
/dev/crtO /dev/crtl 
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Whereas for a logical screen that is two screens tall by one screen wide, the syntax 
would be: 

SingleLogicalScreen 2 1 
/dev/crtO /dev/crtl 

Supported SLS Configurations 

■ Series 712 with an Integrated Color Graphics + plug-in Color Graphics 

■ Series 715 with an Integrated Color Graphics -|- plug-in Color Graphics 

■ Series 720 with a Dual CRX 

■ Series 725 with an Integrated Color Graphics -|- plug-in Color Graphics 

■ Series 730 with a Dual CRX 

■ Series 735 with a Dual CRX 

■ Series 750/755 with a Dual CRX 

■ Series 750/755 with two Dual CRXs 

■ Series 750/755 with two CRX24s 

■ Series 750/755 with two CRX24Zs 

■ Series 770 with two HCRX24s 

■ Series 770 with a Duet 

HP VUE and Single Logical Screen 

Please note that HP VUE has not been modihed to take advantage of the Single 
Logical Screen capability. When presenting information on your display, HP VUE 
may split a window across physical screens. Examples include: 

■ The login screen. 

■ The Eront Panel. 

■ Window move and resize boxes. 

■ The screen lock dialog. 

This behavior is the result of HP VUE’s naive assumption that it is running 
against one large screen; it centers these windows accordingly. 

If you are using the default HP VUE key bindings, you can easily reposition the 
Eront Panel so that it is completely contained within one physical screen: 

1. With the input focus on the Eront Panel, press fAit ~ K Space] (on older keyboards, 
use [Extend Char] [Space] ). 

2. With the Eront Panel menu posted and the “Move” menu item selected, press 
[Enter] (ou older keyboards, [Return] ) to start the move. 
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3. Use the mouse or the arrow keys to reposition the Front Panel to the desired 
location. 

4. Press [Enter ] (or [Return ] ) to Complete the move. You may instead press f isT] to 
cancel the move. 

Afterwards, this setting will be remembered and restored at your next login. If 
you have previously set a Home session, you will need to re-set the Home session 
in the Style Manager to register the new Front Panel position. 

Note that there is no mechanism in HP VUE for repositioning the login screen, 
window move/resize boxes, or the screen lock dialog. 

HP Color Recovery 

Color Recovery is a technique that generates a better picture by eliminating the 
graininess caused by traditional dithering techniques. It is available on these 
graphics devices: 

■ Integrated Color Graphics and plug-in Color Graphics cards 

■ HCRX: HCRX-8[Z], HCRX-24[Z], HP Visualize-8, HP Visualize-24, 

HP Visualize-48 

Color Recovery is available when using either PseudoColor or depth-8 TrueColor 
visuals. 

There are two components to the Color Recovery process. First, a different 
dither-cell size (16x2) is used when rendering shaded polygons. Second, a digital 
hlter is used when displaying the contents of the frame buffer to the screen. 

Under some conditions. Color Recovery can produce undesirable artifacts in the 
image (this also happens with dithering, but the artifacts are different). However, 
images rendered with Color Recovery are seldom worse than what dithering 
produces. In most cases. Color Recovery produces signihcantly better pictures 
than dithering. 

Color Recovery is available by default for all depth-8 color visuals on devices 
that support the feature. If, for some reason, you wish to disable Color Recovery, 
set the HP_DISABLE_COLOR_RECOVERY environment variable to any value before 
starting the server. 

Color Recovery is enabled in conjunction with a particular X colormap that is 
associated with your window. If the X colormap is not installed in hardware, 
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you may not see the effect of the Color Recovery hlter (you may not even see the 
correct colors for that window). Given that more than one hardware colormap 
(or “color lookup table”) is available, this should happen infrequently. 

The Color Recovery colormap is a read-only colormap. Any attempts to change 
it will be ignored and no error will be reported. 

Access to the Color Recovery capability is transparent when using a 3D graphics 
API such as Starbase, HP-PHIGS or PEX. If you are producing graphics using 
Xlib calls, your application must perform some of the necessary processing. 
The method to access Color Recovery via Xlib is described in a section called 
“Accessing HP Color Recovery Technology via Xlib” in the device-dependent 
sections. 

Dynamic Loading 

HP’s X server now dynamically loads the appropriate device drivers and 
extensions based on the target graphics display device and the extensions it 
supports. This feature should be transparent to X server users. 

The extension/device relationships are explained in the extension specihc sections 
of this hie. 


Note 



Altering or removing hies under /usr/lib/Xll/Xserver may 
prevent the X server from running. 


Shared Memory Usage 

Graphics processes use shared memory to access data pertaining to the display 
device and Xll resources created by the server. (“Resources” includes windows, 
colormaps, and cursors.) The Xll server initiates an independent process 
called the Graphics Resource Manager (GRM) to manage these resources among 
graphics processes. Graphics processes include PEXlib, PHIGS, and Starbase 
applications. One problem encountered with GRM shared memory is that it may 
not be large enough to run some applications. 

Graphics applications that require VM double-buffering (for example, when the 
HP_VM_DOUBLE_BUFFER environment variable is used) use large amounts of shared 
memory. Shared memory can be completely consumed by several double-buffered 
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graphics windows. When an application attempts to use more shared memory 
than is available, the application encounters errors and might terminate. 

You can circumvent the problem by using environment variables to change the 
shared memory size. 

Changing Graphics Shared Memory Size 

The size of the shared memory segment used by the GRM can be controlled 
through an environment variable. The default value is 0x580000 (5.5 Mbytes) on 
Series 700 computers. 


Note 



The actual GRM shared memory size on a system can be 
determined by running “ipcs -ma”, hnding the entry with GRID 
matching the process ID of the grmd process and then checking 
the segment size (SEGSZ) held. 


If more shared memory space is needed, graphics shared memory size can be 
increased. For example, to set it to eight megabytes in ksh: 

export GRM_SIZE=0x800000 

Note that the value must be in hexadecimal. The new value won’t take effect 
until you restart the Xll server. 

It is also possible to decrease the size of GRM shared memory. You may want to 
do this if you want to reduce the swap space requirements of your system and/or 
you do not intend to run any 3D graphics processes. For example, you could 
reduce graphics shared memory size to 0x100000 (one megabyte). 

Count Transparent In Overlay Visual 

In some conhgurations, an 8-plane overlay visual may have less than 256 colors. 
This should not cause a problem for most applications. If an application depends 
on 8-plane visuals having 256 colormap entries, this option may be useful. Setting 
this option to any value will cause the X server to count transparent entries in 
the number of colormap entries. 

Examples of Relevant Graphics Devices: CRX-24[Z], CRX-48Z, HCRX-8[Z], 
HCRX-24[Z], HP Visualize-8, HP Visualize-24, HP Visualize-48 
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Environment Variable To Use: HP_COUIT_TRAISPAREIT_II_OVERLAY_VISUAL 

Enable Overlay Transparency 

This option is used to enable the usage of an overlay transparent color on devices 
that can support it, but, by default, do not allow it (for example, HCRX-8). 

Examples of Relevant Graphics Device: HCRX-8[Z], HP VlsUALlZE-8 

Environment Variable To Use: HP_EMBLE_OVERLAY_TRAISPAREICY 

The variable may be set to any value before starting the X server. 

Note that setting this variable will cause the number of colormaps to drop to one 
in the Overlay planes and one in the Image planes. See the section on the HCRX 
family of devices for more information. 

3-Bit Center Color 

This option is available to force the X server to center colors in the colormap 
to values that will reduce the amount of twinkle on flat-panel conversion. This 
option applies only to flat-panel displays. 

The twinkling effect is caused by the analog-to-digital conversion. Due to noise 
in the analog signal, it is possible for a color near a boundary between two digital 
values to cause the conversion to bounce back-and-forth between the two colors 
(i.e., twinkle). In order to avoid this effect, the server “centers” the colors as far 
from the color boundaries as possible. 

Examples of Relevant Graphics Device: Integrated Color Graphics, Color 
Graphics cards. Internal Color Graphics 

Environment Variable To Use: HP_3_BIT_CEITERC0L0R 

The variable may be set to any value before starting the X server. 

Image Text Via BitMap 

When using the Xlib XDrawImageStringO call to draw text, a visual effect may 
be seen where text appears to flicker as the background and foreground are drawn 
in distinct graphics operations. This option is available to eliminate the flicker 
effect but at the expense of reduced text performance. The option will make 
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the X server first draw text to an ofF-screen pixmap prior to displaying it to the 
screen. 

Examples of Relevant Graphics Device: Integrated Color Graphics, Color Graph¬ 
ics cards, CRX-24[Z], CRX-48Z, HCRX-8[Z], HCRX-24[Z], HP Visualize-8, HP 
Visualize-24, HP Visualize-48 

Environment Variable To Use: HPGCRX_IMAGETEXT_VIA_BITMAP 
The variable may be set to any value before starting the X server. 


Note 



Using this option will reduce text performance. 
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Obsolete Environment Variables 

These environment variables are no longer supported: 

■ HP_SUPPRESS_TRUECOLOR_VISUAL 

■ HP_COLORMAP_MAIAGEMEIT_SCHEME 

These environment variables are being replaced and may not be supported in 
future releases: 

■ Old Name: WMSHMSPC 
New Name: GRM.SIZE 

■ Old Name: MBX_SWAP_BUFFERS_OI_VBLAIK 
New Name: SWAP_BUFFERS_OI_VBLAIK 

■ Old Name: CRX24_C0UIT_TRAISPAREIT_II_0VERLAY_VISUAL 
New Name: HP_COUIT_TRAISPAREIT_II_OVERLAY_VISUAL 

Special Device Files 

Special device files are used to communicate between the computer and peripheral 
devices. The X server requires the use of a special device file for each graphics 
card present in the system. 

Special device files are created with the mknod command. The mknod command 
resides in /etc and may only be invoked by a superuser (i.e., root). Although 
special device files can be made in any directory of the HP-UX file system, the 
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convention is to create them in the /dev directory. Any name may be used for 
the special device hie; however, the names that are suggested for the devices 
are crt, crtO, crtl, crt2, or crt3. It is also acceptable to use a name that is 
descriptive of the graphics device, for example, crtl.left or crtl.right. The 
usage statement for the mknod command is: 

mknod: arg count 

usage: mknod name b|c major minor [ cnode ] 
mknod name p 

All graphics special device hies are character device hies with read-write 
permissions by all. For 9.0a; systems, the major number will always be 12. 
The following table, in which the leading “Ox” indicates that the number is in 
hexadecimal format, indicates which minor numbers to use for creating alternate 
device hies. 


Table 3-2. Special Device Files: Minor Numbers 


Device 

Filename 

9.Ox Minor 
Nnmber 

Description 

/dev/crt 

0x100000 

Standard console device hie 

/dev/crt.r 

0x100000 

Dual CRX Graphics console, right device 

/dev/crt.1 

0x100004 

Dual CRX Graphics console, left device 

/dev/hcrx 

0x000000 

Secondary graphics device hie 

/dev/freedom 

0x000000 

Freedom Series, secondary graphics device hie 

/dev/crtl.r 

0x000000 

Secondary graphics device is Dual CRX Graphics, 
right device 

/dev/crtl.1 

0x000004 

Secondary graphics device is Dual CRX Graphics, 
left device 


Following are some examples of using the mknod entry for the HP-UX Operating 
System. 

For an SPU with only one SGC interface slot (e.g., a Model 720) running Dual 
CRX graphics, a sample 9.07 mknod entry for the second graphics device would 
be: 


/etc/mknod /dev/crtO.left c 12 0x000004 
chmod 666 /dev/crtO.left 
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For an SPU with two SGC interface slots, a sample mknod entry for the other 
slot would be: 

/etc/mknod /dev/crtl.right c 12 0x000000 
chmod 666 /dev/crtl.right 

Note that once the device hie has been created, it is necessary to ensure that it 
has read-write permissions by all; i.e., “chmod 666”. 
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Supported X Configurations 

Supported Graphics Devices 

The table below summarizes the graphics devices that are supported on each of 
the HP9000 Series systems: 
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Table 3-3. Graphics Devices Supported on HP-UX 9.x 


Graphics Devices 

Supported HP 9000 Models 

Integrated GrayScale 
Graphics^ 

712 (all models), 715/64, 715/80, 715/100, 725/100 

Integrated Golor 
Graphics^ 

712 (all models), 715/64, 715/80, 715/100, 725/100, 

7481^4, 7481/100, V743/64, V743/100 

Golor Graphics card 

712 (all models), 715/64, 715/80, 715/100, 725/100, 

7481^4, 7481/100, J200, J210 

Dual Golor Graphics 
card 

715/64, 715/80, 715/100, 725/100, J200, J210 

Internal GrayScale 
Graphics^ 

705, 710, 715/33, 715/50, 715/75, 725/50, 725/75 

Internal Golor Graphics^ 

705, 710, 715/33, 715/50, 715/75, 725/50, 725/75, 7451/50, 
7451/100, 7471/50, 7471/100 

GRX, Dual GRX 

720, 730, 735, 735/125, 750, 755, 755/125, 747i/50, 

7471/100 

GRX 

720, 730, 735, 735/125 

GRX-24 

715/33, 715/50, 715/75, 720, 725/50, 725/75, 730, 735, 
735/125, 747i/50, 7471/100, 750, 755, 755/125 

GRX-24Z 

715/33, 715/50, 715/75, 720, 725/50, 725/75, 730, 735, 
735/125, 750, 755, 755/125 

GRX-48Z 

715/50, 715/75, 715/100, 725/50, 725/75, 725/100, 735, 
735/125, 755, 755/125, J200, J210 

HGRX-8, HGRX-8Z, 
HGRX-24, HGRX-24Z, 
HP Visualize-8, 

HP Visualize-24 

715/64, 715/80, 715/100, 725/100, J200, J210 

Person alVRX, 

TurboVRX 

720, 730, 735, 735/125, 750, 755, 755/125 (no longer on the 
Gorporate Price List) 

Freedom Series(TM) 
Graphics (S3150, S3250 
and S3400) 

715/80, 715/100, J200, J210 

HP Visualize-48 

J200, J210 
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^ Integrated Gray Scale Graphics and Internal Gray Scale Graphics is 

supported on high-resolution (1280x1024) for all Models specihed above. 

^ Integrated Color Graphics and Internal Color Graphics are supported on 

both medium-resolution (1024x768) and high-resolution (1280x1024) 
conhgurations of the Series 700 Models 705, 710, 712 (all models), and 
715/33. High resolution is supported on all other Models specihed above. 

Multi-Display Support 

The following dehnitions are included to help alleviate confusion between the 
terms multi-display, multi-screen, multi-seat, and single logical screen. 

■ Multi-Display: A conhguration with multiple graphics devices (displays) used 
concurrently. Any multi-seat or multi-screen conhguration is referred to as a 
multi-display conhguration. 

■ Multi-Screen: A conhguration in which a single X server with a mouse and 
keyboard drives multiple graphics devices (where each head is a different Xll 
screen) concurrently while only allowing the cursor, not windows, to be moved 
between heads. 

■ Multi-Seat: A conhguration with multiple instantiations of the X server, each 
with its own mouse, keyboard, and heads. Multi-seat is not supported on the 
HP-UX 9.0a; release. 

■ Single Logical Screen: A conhguration in which a single X server with a single 
mouse and keyboard drives multiple homogeneous graphics devices (heads) 
concurrently while allowing the heads to emulate a large single screen. This 
differs from a multi-screen environment by allowing windows to be moved and 
displayed across heads. See the section in this document on Single Logical 
Screen. 

Note that different monitor resolutions are not supported with multi-display 
conhgurations. 

Multi-Screen Support 

This section refers to multi-screen conhgurations only. Running one X server 
on more than one graphics display is called a “multi-screen” operation. The 
keyboard and pointer are shared among the screens. Multiple screens are enabled 
via the /usr/lib/Xll/X*screens hie. The X*screens hie is used to conhgure 
the operation of the X server. The screens are dehned in the X*screens hie by 
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specifying the appropriate special device files. See the section in this document 
on special device hies and /usr/lib/Xll/XOscreens for more information. 


A separate screen entry for each graphics display is entered in the X*screens hie. 
The order of entries determines each screen number starting at 0. The devices 
can be arranged in any order. 

For example, in the following multi-screen system, the screen numbers are 
assigned as indicated: 

/dev/crtl # first entry is screen 0 (as in localrO.O) 
/dev/crtO # second entry is screen 1 (as in local:0.1) 
/dev/crt2 # third entry is screen 2 (as in local:0.2) 


The X server supports up to four screens at a time. Specifying more than four 
screens will cause a server error message. 

The following multi-screen conhgurations are supported (unless otherwise stated, 
different resolutions are not supported with multi-display conhgurations): 

■ 712/60 and 712/80: 

□ Integrated Color Graphics and one plug-in Color Graphics card. 

■ 715/33: 

□ Internal Color Graphics and one CRX-24 

□ Internal Color Graphics and one CRX-24Z 

■ 715/50, 715/75, 725/50, and 725/75: 

□ Internal Color Graphics and one CRX-24 

□ Internal Color Graphics and one CRX-24Z 

□ Internal Color Graphics and one CRX-48Z 

■ 715/64, 715/80, and 715/100: 

□ Integrated Color Graphics and one plug-in Color Graphics card. 

□ Integrated Color Graphics and one Dual Color Graphics card 

□ Integrated Color Graphics and one HCRX-24 

□ Integrated Color Graphics and one HCRX-24Z 

□ Integrated Color Graphics and one HP VlsUALlZE-24 

725/100: 

□ Integrated Color Graphics and up to two plug-in Color Graphics cards 

□ Integrated Color Graphics and one Dual Color Graphics card 

□ Integrated Color Graphics and one HCRX-24 

□ Integrated Color Graphics and one HCRX-24Z 

□ Integrated Color Graphics and one HP VlsUALlZE-24 
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720, 730, 735, and 735/125: 

□ One Dual CRX 
7481/64 and 7481/100: 

□ Integrated Color Graphics and one plug-in Color Graphics card (3x5) 

□ Two plug-in Color Graphics cards (3x5) 

7471/50 and 7471/100: 

□ One Dual CRX 

□ Internal Color Graphics and one Dual CRX 
750, 755 and 755/125: 

□ One Dual CRX 

□ Two Dual CRXs 

□ Two CRX-24s 
J200 and J210: 

□ Up to four screens with any combination of plug-in Color Graphics cards and 
Dual Color Graphics cards 

■ One or two Dual Color Graphics cards 

■ Up to three plug-in Color Graphics cards 

■ One Dual Color Graphics card and up to two plug-in Color Graphics cards 

□ Two HCRX-24 cards 

□ One plug-in Color Graphics card and one HCRX-24Z 

□ One plug-in Color Graphics card and one HP VlsUALlZE-24 

□ One plug-in Color Graphics card and one CRX-48Z 
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Integrated Color Graphics Device-Dependent Information 

This sections includes information on Integrated Color Graphics, Color Graphics, 
and Dual Color Graphics cards. 

Supported Visuals 

For color displays: 

■ Class Pseudocolor Depth 8: 
supports DBF and MBX software double-buffering 

■ Class TrueColor Depth 8: 
supports DBF and MBX software double-buffering 

For grayscale displays, only one visual is supported: 

■ Class Grayscale Depth 8: 
supports DBF and MBX software double-buffering 

Supported Environment Variables 

The following environment variables are supported: 

■ SWAP_BUFFERS_OI_VBLAIK 

■ HP_DISABLE_COLOR_RECOVERY 

■ HP_3_BIT_CEITERC0L0R 

■ HPGCRX_IMAGETEXT_VIA_BITMAP 

Colormaps and Colormap Management 

Color Graphics devices have two hardware colormaps (color lookup tables), each 
with 256 entries. The X server controls the allocation and contents of these 
hardware colormaps. 

The Default Colormap Management Scheme 

Many applications use the default Xll colormap. A “technicolor” effect in 
the windows using the default colormap occurs when a non-default colormap 
is downloaded into the hardware colormap that had previously contained the 
default colormap. 
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Because so many applications use the default Xll colormap—including the 
window manager—and because Color Graphics devices have two hardware 
colormaps, the default behavior on this device is to dedicate one hardware 
colormap to always hold the default Xll colormap. The second hardware 
colormap is available to applications that use colormaps other than the default. 

The default behavior can cause technicolor if two or more applications are using 
different, non-default colormaps. For example, Application A uses the default 
Xll colormap. Application B uses a different colormap, and Application C uses 
a third colormap. If applications A, B, and C are all executed simultaneously on 
a Model 712, application A would look correct. Either application B or C would 
have a technicolor effect—the application whose colormap was last downloaded 
into the hardware colormap would look correct. 

Accessing HP Color Recovery Technology via Xlib 

Color Recovery is a technique to generate a better picture by attempting to 
eliminate the graininess caused by dithering. Access to the Color Recovery 
capability is transparent when using a 3D graphics API such as Starbase, HP- 
PHIGS or PEX. If you are producing graphics using Xlib calls, your application 
must perform some of the necessary processing. At server startup (if Color 
Recovery is not disabled in the X*screens hie), the following properties are dehned 
and placed on the root window: 

■ _HP_RGB_SMOOTH_TRUE_MAP 

■ _HP_RGB_SMOOTH_PSEUDO_MAP 

■ _HP_RGB_SMOOTH_MAP_LIST 

These properties are of type RGB_C0L0R_MAP and carry pointers to struc¬ 
tures of type XStandardColormap. They may be interrogated with calls to 
XGetRGBColormaps. The colormaps in the _HP_RGB_SMOOTH_TRUE_MAP and 
_HP_RGB_SMOOTH_PSEUDO_MAP structures identify colormaps which are created 
at server startup and are for use with the TrueColor and PseudoColor visuals, 
respectively. They are both initialized to contain the 3:3:2 ramp of 8-bit True- 
Color. Neither of these colormaps can be modihed, as they are read-only. The 
property _HP_RGB_SMOOTH_MAP_LIST is a list of colormaps that are associated 
with window visual IDs that support Color Recovery. When the XGetRGBCol¬ 
ormaps routine searches through this list for a colormap with a visual ID that 
matches your window’s visual ID and it hnds one, your application knows that 
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your visual supports Color Recovery, and uses that colormap for any Color Re¬ 
covery window in your window’s visual. 

Note that the algorithm used for the Color Graphics device is slightly different 
from that used for the HCRX family of devices. If you do not wish for your 
application to have to do device-specihc checks, HP recommends that you use 
the HCRX encoding algorithm for Color Recovery regardless of the device on 
which your application is executing. The results on the Color Graphics device 
will not be optimal, but will generally still be much better than a standard 
dither. If you are willing to do device-specihc checks, the existence of either 
the _HP_RGB_SMOOTH_TRUE_MAP or _HP_RGB_SMOOTH_PSEUDO_MAP property will 
indicate the device is Color Graphics. 

Color Recovery uses all 256 entries of one of the available colormaps. The color 
visual used by Color Recovery emulates the 24-bit TrueColor visual, thus, the 
colors red, green, and blue are typically declared as integers in the range from 
0 to 255. Note that each window that uses Color Recovery will have the same 
colormap contents. 

For Color Recovery to produce the best results, the emulated 24-bit TrueColor 
data is dithered as explained below. 

A pixel to be dithered is sent to the routine provided in this example. Note that 
the values of the variables RedValue, GreenValue, and BlueValue are generated 
by an application. In this example, the color values are assumed to be in the 
range 0..255. 

The given routine receives the color values and the X and Y window address (Xp 
and Yp) of the pixel. The X and Y address is used to access the dither tables. 
The values from the dither tables are added to the color values. After the dither 
addition, the resultant color values are quantized to three bits of red and green 
and two bits of blue. The quantized results are packed into an 8-bit unsigned 
char and then stored in the frame buffer. In the process of sending the contents 
of the frame buffer to the CRT, a special section in the hardware then converts 
the frame buffer’s 8-bit data into a 24-bit TrueColor data for display. 

Here is a routine that can be used to dither the 24-bit TrueColor data. 

unsigned char dither_pixel_for_CR(RedValue, GreenValue, BlueValue, Xp, Yp) 
int RedValue, GreenValue, BlueValue, Xp, Yp; 

{ 

static short dither_red[2][16] = { 

{-16, 4, -1, 11,-14, 6, -3, 9,-15, 5, -2, 10,-13, 7, -4, 8}, 
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{ 15, -5, 0, 

-12, 

13, -7, 2,-10, 14, -6, 

1, 

-11, 

12, 

-8, 

3, 

-9}}; 

static short 
{ 11,-15, 7, 

-3, 

dither_green[2][16] = { 
8,-14, 4, -2, 10,-16, 

6, 

-4, 

9, 

-13, 

5, 

-1}, 

{-12, 14, -8, 

2, 

-9, 13, -5, 1,-11, 15, 

-7, 

3, 

-10, 

, 12, 

-6, 

0}}; 

static short 
{ -3, 9,-13, 

7, 

dither.blue[2][16] = { 
-1, 11,-15, 5, -4, 8,- 

-14, 

6, 

-2, 

10, 

-16, 

4}, 

{ 2,-10, 12, 

-8, 

0,-12, 14, -6, 3, -9, 

13, 

-7, 

1, 

-11, 

15, 

-5} } 


int red, green, blue; 

int x_dither_table, y_dither_table; 

unsigned char pixel; 


/* Determine the dither table entries to use based on the pixel address */ 
x_dither_table = Xp */, 16; /+ X Pixel Address MOD 16 +/ 

y_dither_table = Yp */, 2; /+ Y Pixel Address MOD 2 +/ 


/* Start with the initial values as supplied by the calling routine */ 
red = RedValue; 
green = GreenValue; 
blue = BlueValue; 


/* Generate the red dither value */ 

red += dither_red[y_dither_table][x_dither_table]; 

/* Check for overflow or underflow on red value */ 
if (red > Oxff) red = Oxff; 
if (red < 0x00) red = 0x00; 

/* Generate the green dither value */ 

green += dither_green[y_dither_table][x_dither_table]; 

/* Check for overflow or underflow on green value */ 
if (green > Oxff) green = Oxff; 
if (green < 0x00) green = 0x00; 

/* Generate the blue dither value */ 

blue += (dither_blue[y_dither.table][x_dither_table]<<1); 

/* Check for overflow or underflow on blue value */ 
if (blue > Oxff) blue = Oxff; 
if (blue < 0x00) blue = 0x00; 

/* Generate the pixel value by "or"ing the values together */ 

pixel = ((red & OxEO) | ((green & OxEO) >> 3) | ((blue & OxCO) >> 6)); 

return(pixel); 
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Internal Color Graphics, Internal Grayscale Graphics, 
CRX, GRX, andDual-CRX Device-Dependent Information 


Supported Visuals 

Only one visual is supported. 

For color displays: 

■ Class Pseudocolor Depth 8: 

supports DBF and MBX hardware double-buffering (CRX, Dual CRX); 
supports DBF and MBX software double-buffering (Internal Color Graphics). 

For grayscale displays: 

■ Class Grayscale Depth 8: 

supports DBF and MBX hardware double-buffering (GRX); supports DBF and 
MBX software double-buffering (Internal GrayScale Graphics). 

Supported Environment Variables 

The following environment variables are supported: 

■ SWAP_BUFFERS_OI_VBLAIK 

■ HP_3_BIT_CEITERC0L0R (Internal Color Graphics only) 

■ HPGCRX_IMAGETEXT_VIA_BITMAP 
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CRX-24[Z] Device-Dependent Information 


Supported Visuals 

The following visuals are supported: 

■ Class Pseudocolor Depth 8 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class Pseudocolor Depth 8 Layer Overlay: 
supports DBE and MBX software double-buffering 

■ Class DirectColor Depth 12 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class TrueColor Depth 12 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image: 

does not support DBE and MBX double-buffering 

■ Class TrueColor Depth 24 Layer Image: 

does not support DBE and MBX double-buffering 

Supported Environment Variables 

The following environment variables are supported: 

■ SWAP_BUFFERS_OI_VBLAIK 

■ HP_COUIT_TRAISPAREIT_II_OVERLAY_VISUAL 

■ HPGCRX_IMAGETEXT_VIA_BITMAP 

CRX-24[Z] Transparent Overlay Visuals 

The default number of colormap entries in the overlay visual for the CRX-24[Z] 
is 255. Entry 255 is excluded because its value is hard-coded to transparent (that 
is, show the image planes). 

This may have the following two consequences for Xll applications running in 
the overlay planes (the default visual): 

■ Clients attempting to allocate 256 entries do not have their request granted. 

■ Clients requesting (via XAllocNamedColor) the rgb.txt value of Transparent 
are not returned entry 255. 
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This default behavior can be changed by setting the environment variable 
HP_COUIT_TRAISPAREIT_II_OVERLAY_VISUAL to any value. When this option 
is enabled, the X server does the following: 

■ Specihes that the overlay visual has 256 entries. 

■ Creates the default colormap with entry 255 pre-allocated to Transparent. A 
client calling XAllocNamedColor for entry Transparent in the default colormap 
will be returned entry 255. 

■ For all other colormaps, returns all 256 entries as allocable, but issues a warning 
message: 

Warning: XCreateColormap is creating 256 entry cmaps in overlay visual. 

Though allocable, entry 255 is hard-coded to transparency. 


This warning is issued once per server execution. 
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CRX-48Z Device-Dependent Information 


Supported Visuals 

The following visuals are supported: 

■ Class PseudoColor Depth 8 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay: 
supports DBE and MBX software double-buffering 

■ Class DirectColor Depth 24 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class TrueColor Depth 24 Layer Image: 
supports DBE and MBX hardware double-buffering 

Supported Environment Variables 

The following environment variables are supported: 

■ SWAP_BUFFERS_OI_VBLAIK 

■ HP_COUIT_TRAISPAREIT_II_OVERLAY_VISUAL 

■ HPGCRX_IMAGETEXT_VIA_BITMAP 

CRX-48Z Transparent Overlay Visuals 

The default number of colormap entries in the overlay visual for the CRX-48Z is 
255. Entry 255 is excluded because its value is hard-coded to transparent (that 
is, show the image planes). 

This may have the following two consequences for Xll applications running in 
the overlay planes (the default visual): 

■ Clients attempting to allocate 256 entries do not have their request granted. 

■ Clients requesting (via XAllocNamedColor) the rgb.txt value of Transparent 
are not returned entry 255. 

This default behavior can be changed by setting the environment variable 
HP_COUIT_TRAISPAREIT_II_OVERLAY_VISUAL to any value. When this option 
is enabled, the X server does the following: 

■ Specihes that the overlay visual has 256 entries. 
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■ Creates the default colormap with entry 255 pre-allocated to Transparent. A 
client calling XAllocNamedColor for entry Transparent in the default colormap 
will be returned entry 255. 

■ For all other colormaps, returns all 256 entries as allocable, but issues a warning 
message: 

Warning: XCreateColormap is creating 256 entry cmaps in overlay visual. 

Though allocable, entry 255 is hard-coded to transparency. 


This warning is issued once per server execution. 


3 
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HCRX Device-Dependent Information 

This section includes information on the HCRX-8[Z] and HCRX-24[Z] devices, 
and the HP VisuALiZE-8, HP Visualize-24, and HP Visualize-48 devices. 

The HCRX-8[Z] is a one board device (two, with the optional accelerator that 
has eight overlay planes, two banks of 8 image planes, and 4 hardware colormaps. 
This device provides a superset of functionality in the CRX. 

The HCRX-24[Z] is a one board device (two, with the optional accelerator) that 
has eight overlay planes, two banks of 12 image planes, and 4 hardware colormaps. 
This device provides a superset of functionality in the CRX-24[Z]. 

The HP Visualize-8 is a two board accelerated device that has eight overlay 
planes, two banks of 8 image planes, and 4 hardware colormaps. This device 
provides a superset of functionality in the CRX. 

The HP Visualize-24 is a two board accelerated device that has eight overlay 
planes, two banks of 12 image planes, and 4 hardware colormaps. This device 
provides a superset of functionality in the CRX-24[Z]. 

The HP Visualize-48 is a two-board accelerated device (three, with the optional 
texture- mapping hardware) that has eight overlay planes, two banks of 24 
image planes, and six hardware colormaps. This device provides a superset of 
functionality in the CRX-48Z. The hardware support for accelerating 2D Xlib 
primitives is similar to that in the other HCRX devices. The hardware for 
accelerating 3D geometry, lighting, and shading, is new. 

Supported Visuals 

The following visuals are supported on the HCRX-8[Z] and HP VlsUALlZE-8: 

■ Class Pseudocolor Depth 8 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class Pseudocolor Depth 8 Layer Overlay: 

(see Note) supports DBE and MBX software double-buffering 

■ Class Pseudocolor Depth 8 Layer Overlay Transparent: 

(see Note) supports DBE and MBX software double-buffering 

■ Class TrueColor Depth 8 Layer Image: 

supports DBE and MBX hardware double-buffering 
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Note 



The two overlay visuals are mutually exclusive, based on the 
presence of the HP_EIABLE_OVERLAY_TRAISPAREICY environment 
variable (i.e., if the HP_EMBLE_OVERLAY_TRAISPAREICY environ¬ 
ment variable is set, then the visual that supports transparency 
is available, otherwise the visual which does not support trans¬ 
parency is available). 


The following visuals are supported on the HCRX-24[Z] and HP VlsUALlZE-24: 

■ Class Pseudocolor Depth 8 Layer Image: 3 

supports DBE and MBX hardware double-buffering 

■ Class Pseudocolor Depth 8 Layer Overlay: 
supports DBE and MBX software double-buffering 

■ Class Pseudocolor Depth 8 Layer Overlay Transparent: 
supports DBE and MBX software double-buffering 

■ Class TrueColor Depth 8 Layer Image: 

supports DBE and MBX hardware double-buffering 

■ Class DirectColor Depth 12 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class TrueColor Depth 12 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image: 

does not support DBE and MBX double-buffering 

■ Class TrueColor Depth 24 Layer Image: 

does not support DBE and MBX double-buffering 

The following visuals are supported on the HP VlsUALlZE-48: 

■ Class Pseudocolor Depth 8 Layer Image: 
supports DBE and MBX hardware double-buffering 

■ Class Pseudocolor Depth 8 Layer Overlay: 
supports DBE and MBX software double-buffering 

■ Class Pseudocolor Depth 8 Layer Overlay Transparent: 
supports DBE and MBX software double-buffering 

■ Class TrueColor Depth 8 Layer Image: 

supports DBE and MBX hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image: 
supports DBE and MBX hardware double-buffering 
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■ Class TrueColor Depth 24 Layer Image: 
supports DBE and MBX hardware double-buffering 

Supported Environment Variables 

The following environment variables are supported: 

■ SWAP_BUFFERS_OI_VBLAIK 

■ HP_DISABLE_COLOR_RECOVERY 

■ HP_COUIT_TRAISPAREIT_II_OVERLAY_VISUAL 

■ HP_EMBLE_OVERLAY_TRAISPAREICY (HCRX-8[Z] and HP VlsUALlZE-8 only) 

■ HPGCRX_IMAGETEXT_VIA_BITMAP 

HCRX Configuration Hints 

HCRX-8[Z] and HP Visualize-8 Visuals and Double-Buffer Support 

The 8-plane HCRX-8[Z] and HP VlsUALlZE-8 are the hrst members of the Series 
700 graphics family whose overlay planes and image planes are both depth 8. 

■ There are two depth-8 PseudoColor visuals (one in the overlay planes, the 
other in the image planes). There is also a depth-8 TrueColor visual in the 
image planes. 

■ The default visual (where the root window and default colormap reside) is in 
the overlay planes. 

■ Fast 8/8 double-buffering (two hardware buffers) is supported in the depth-8 
image planes, but not in the overlays. The overlay planes support the slower 
virtual-memory-based double-buffering. 

Implications and Suggestions for HCRX-8[Z] and HP Visualize-8 

The default colormap cannot be used with a window in a non-default visual, even 
one of the same depth as the default visual. 

Before trying to use the default colormap in a depth-8 window, verify that the 
window is in the default visual. If the window is not in the default visual, create 
a colormap in that visual. This process is the same as the one used to create 
windows in depth-12 or depth-24 visuals. 
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Unlike the CRX, the HCRX-8[Z]’s default visual and the HP VlsUALlZE-8’s 
default visual do not have fast hardware double-buffering (but the image planes 
do). 

To obtain hardware double-buffering, hnd a visual in the image planes. The 
best method is to hnd all the depth-8 PseudoColor visuals returned by 
XGetVisualInfo and then eliminate the visuals that are reported in the 
SERVER_OVERLAY_VISUALS property (discussed below). 

HCRX Overlay Visuals and Overlay Transparency 

As on the CRX-24[Z] and CRX-48Z, the SERVER_OVERLAY_VISUALS property on 
the root window is used to describe the visuals that are in the overlay planes. 

Overlay Transparency on the HCRX-8[Z] and HP Visualize-8 

The 8-plane HCRX-8[Z] and the 8-plane HP VlsUALlZE-8 both have one visual 
in the overlay planes (depth-8 PseudoColor). By default, these overlay visuals 
have no transparent index available to applications for rendering transparency. 
This means the overlay windows with “hoating text” are not supported in the 
typical X server operation on the HCRX-8[Z] or HP VlsUALlZE-8. 

For applications that require transparent overlay windows on the HCRX-8[Z] or 
HP Visualize-8, an optional X server mode is available to allow for overlay 
transparency, but it is restrictive. In this optional mode, overlay colormaps 
provide a single entry that can be used to render transparency. Only one hardware 
colormap is available in the overlays (instead of two) and only one hardware 
colormap is available in the image planes (instead of two). 

To activate this optional X server mode to enable transparency, set the 
environment variable HP_EIABLE_OVERLAY_TRAISPAREICY to any value. You will 
need to restart the X server for the option to take effect. 

With this mode enabled, colormaps created in the default visual have 255 entries; 
entry 256 is reserved for transparency. As on the CRX-24[Z] and CRX-48Z, the 
environment variable HP_EIABLE_OVERLAY_TRAISPAREICY can be used to include 
the transparent index in the colormap size (256 entries instead of 255). 

Programmer’s Note If transparency is not enabled, there are only 252 colors 

available. Entries 252-255 are not writable, and should 
not be used; there are only 252 colormap extries available, 
even though the server states that there are 256. 
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Overlay Transparency on the HCRX-24[Z], HP Visualize-24, and -48 

The HCRX-24[Z], HP Visualize-24, and HP Visualize-48 have two visuals in 
the overlay planes, both depth-8 PseudoColor. 

The default overlay visual has 256 entries per colormap and no transparency. 

The second overlay visual has 255 entries per colormap and supports transparency 
in the same way as the CRX-24[Z] and CRX-48Z. As on the CRX-24[Z] and CRX- 
48Z, the environment variable HP_EIABLE_OVERLAY_TRAISPAREICY can be used 
to include the transparent index in the colormap size (256 entries instead of 255). 

To allow applications to determine which visuals are in the overlay planes, both 
overlay visuals are listed in the SERVER_OVERLAY_VISUALS property attached 
to the root window. The default overlay visual has a transparent type of 
“0” (None) while the transparent overlay visual has a transparent type of “1” 

(TransparentPixel). 

If you need an overlay colormap that supports transparency, create the colormap 
using the visual that has transparency in its SERVER_OVERLAY_VISUALS property. 
To look at the contents of this property, you would use code similar to the 
following: 

{ 

typedef struct { 

VisuallD overlayVisuallD; 

Card32 transparentType;/* None, TransparentPixel, TransparentMask */ 

Card32 value; /* Either pixel value or pixel mask */ 

Card32 layer; 

} OverlayVisualPropertyRec; 

OverlayVisualPropertyRec *pOverlayVisuals, *pOVis; 

XVisualInfo getVis; 

XVisualInfo *pVisuals; 

Atom overlayVisualsAtom, actualType; 

/* Get the visuals for this screen and allocate. */ 
getVis.screen = screen; 

pVisuals = XGetVisualInfoCdisplay, VisualScreehWask, ftgetVis, ftnVisuals); 
pOverlayVisuals = (OverlayVisualPropertyRec *) 

malloc ( (size_t)nVisuals * sizeof(OverlayVisualPropertyRec) ); 

/* Get the overlay visual information for this screen. Obtain 
+ this information from the SERVER_OVERLAY_VISUALS property. +/ 
overlayVisualsAtom = XInternAtom(display, "SERVER_OVERLAY_VISUALS", True); 
if (overlayVisualsAtom != None) 

{ 
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/* Since the Atom exists, request the property's contents. */ 
bytesAfter = 0; 

nuitiLongs = ( nVisuals * sizeof(OverlayVisualPropertyRec) + 3 ) / 4; 
XGet¥indowProperty(display, Root¥indow(display, screen), 

overlayVisualsAtom, 0, nuitiLongs, False, 

AnyPropertyType, ftactualType, ftactualFormat, 
ftnumLongs, ftbytesAfter, ftpOverlayVisuals); 
if ( bytesAfter != 0 ) {/* Serious Failure Here */} ; 

/* Loop through the pOverlayVisuals array. */ 

nOVisuals = numLongs/sizeof(OverlayVisualPropertyRec); 
pOVis = pOverlayVisuals; 
while (--nOVisuals >= 0) 

{ 

if ( pOVis->transparentType == TransparentPixel ) 

{/* Found a transparent overlay visual, set ident. aside. */}; 
pOVis++; 

} 

XFree(pOverlayVisuals); 

/* There might be some additional checking of the found 
transparent overlay visuals wanted; e.g., for depth. */ 

} 

XFree(pVisuals); 

} 

This program fragment is not complete; its main purpose is to give the idea of 
how to hnd an overlay visual having transparency. 

HCRX Colormaps 

The following information discusses the number of supported colormaps for the 
HCRX conhgurations. 

HCRX-8[Z] and HP Visualize- 8: Eight Overlay Planes and Two Depth-8 Banks of 
Image Planes. When the environment variable 

HP_EMBLE_OVERLAY_TRAISPAREICY is not set, the overlay planes contain the 
default colormap permanently installed in the hardware, plus one other hardware 
colormap available to applications. The image planes contain two hardware 
colormaps each usable by applications. 

When the environment variable HP_EIABLE_OVERLAY_TRAISPAREICY is set, both 
the overlay planes and the image planes have access to one hardware colormap. 
The default colormap is not permanently installed in the hardware. 
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HCRX-24[Z] and HP Visualize-24: Eight Overlays and 24 Image Planes. The 

overlay planes contain the default colormap permanently installed in the 
hardware, plus one other hardware colormap available to applications. The image 
planes contain two hardware colormaps, each usable by applications. 

Although two hardware colormaps are available to applications in the image 
planes, a hardware restriction allows only one depth-12 or depth-24 colormap 
to be installed at any given time. Therefore, if two applications are run 
simultaneously and use different depth-12 or depth-24 colormaps, the application 
that has the colormap focus looks correct and the other is technicolored. 

HP Visualize-48: Eight Overlay Planes and 48 Image Planes. The overlay planes 
contain the default colormap permanently installed in the hardware, plus one 
other hardware colormap available to applications. The image planes contain 
four hardware colormaps, each usable by applications. 

The four hardware colormaps in the image planes can be treated as depth-8 or 
depth-24 colormaps. There are no restrictions on the types of colormaps that can 
be installed in the hardware at any given time. All four colormaps can be used 
with any visual class. 

Accessing HP Color Recovery Technology via Xlib 

Color Recovery is a technique to generate a better picture by attempting to 
eliminate the graininess caused by dithering. Access to the Color Recovery 
capability is transparent when using a 3D graphics API such as Starbase, HP- 
PHIGS or PEX. If you are producing graphics using Xlib calls, your application 
must perform some of the necessary processing. At server startup (if Color 
Recovery is not disabled in the X*screens hie), the _HP_RGB_SMOOTH_MAP_LIST 
property is dehned and placed on the root window. The above property is of type 
RGB_C0L0R_MAP and carries pointers to structures of type XStandardColormap. 
It may be interrogated with calls to XGetRGBColormaps. The property 
_HP_RGB_SMOOTH_MAP_LIST is a list of colormaps that are associated with window 
visual IDs that support Color Recovery. When the XGetRGBColormaps routine 
searches through this list for a colormap with a visual ID that matches your 
window’s visual ID and it hnds one, your application knows that your visual 
supports Color Recovery, and uses that colormap for any Color Recovery window 
in your window’s visual. 
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Color Recovery uses all 256 entries of one of the available colormaps. The color 
visual used by Color Recovery emulates the 24-bit TrueColor visual, thus, the 
colors red, green, and blue are typically declared as integers in the range from 
0 to 255. Note that each window that uses Color Recovery will have the same 
colormap contents. 

For Color Recovery to produce the best results, the emulated 24-bit TrueColor 
data is dithered as explained below. 

A pixel to be dithered is sent to the routine provided in this example. Note that 
the values of the variables RedValue, GreenValue, and BlueValue are generated 
by an application. In this example, the color values are assumed to be in the 
range 0..255. 

The given routine receives the color values and the X and Y window address (Xp 
and Yp) of the pixel. The X and Y address is used to access the dither tables. 
The values from the dither tables are added to the color values. After the dither 
addition, the resultant color values are quantized to three bits of red and green 
and two bits of blue. The quantized results are packed into an 8-bit unsigned 
char and then stored in the frame buffer. In the process of sending the contents 
of the frame buffer to the CRT, a special section in the hardware then converts 
the frame buffer’s 8-bit data into a 24-bit TrueColor data for display. 

Here is a routine that can be used to dither the 24-bit TrueColor data. 

unsigned char dither_pixel_for_CR(RedValue, GreenValue, BlueValue, Xp, Yp) 
int RedValue, GreenValue, BlueValue, Xp, Yp; 

{ 

static short dither_red[2][16] = { 


{-16, 4, -1, 

11,- 

-14, 6, -3, 9,-15, 

5, -2, 

10, 

-13, 

7, -4, 8}, 

{ 15, -5, 0,- 

12, 

13, -7, 2,-10, 14, 

-6, 1, 

-11, 

12, 

-8, 3, -9}}; 

static short 


dither_green[2][16] 

= { 




{ 11,-15, 7, 

-3, 

8,-14, 4, -2, 10, 

-16, 6, 

-4, 

9,- 

■13, 5, -1}, 

{-12, 14, -8, 

2, 

-9, 13, -5, 1,-11, 

15, -7, 

3, 

-10, 

12, -6, 0}}; 

static short 


dither_blue[2][16] 

= { 




{ -3, 9,-13, 

7, 

-1, 11,-15, 5, -4, 

8,-14, 

6, 

-2, 

10,-16, 4}, 

{ 2,-10, 12, 

-8, 

0,-12, 14, -6, 3, 

-9, 13, 

-7, 

1,- 

■11, 15, -5}}; 

int 


red, green, blue; 





int 


x_dither_table, y_dither_table; 



unsigned char 


pixel; 





/* Determine the 

: dither table entries to use based 

on the pixel addre; 

x_dither_table = 

Xp •/. 16; /* X Pixel 

Address ! 

HOD 

16 +/ 

y_dither_table = 

Yp •/. 2; /* Y Pixel 

Address ! 

WOD 

2 */ 
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/* Start with the initial values as supplied by the calling routine */ 
red = RedValue; 
green = GreenValue; 
blue = BlueValue; 

/* Generate the red dither value */ 

if (red >= 48) /* 48 is a constant required by this routine */ 
red=red-16; 
else 

red=red/2+8; 

red += dither_red[y_dither_table][x_dither_table]; 

/* Check for overflow or underflow on red value */ 

3 if (red > Oxff) red = Oxff; 

if (red < 0x00) red = 0x00; 

/* Generate the green dither value */ 

if (green >= 48) /* 48 is a constant required by this routine */ 
green=green-16; 
else 

green=green/2+8; 

green += dither_green[y_dither_table][x_dither_table]; 

/* Check for overflow or underflow on green value */ 
if (green > Oxff) green = Oxff; 
if (green < 0x00) green = 0x00; 

/* Generate the blue dither value */ 

if (blue >= 112) /* 112 is a constant required by this routine */ 
blue=blue-32; 
else 

blue=blue/2+24; 

blue += (dither_blue[y_dither.table][x_dither_table]<<1); 

/* Check for overflow or underflow on blue value */ 
if (blue > Oxff) blue = Oxff; 
if (blue < 0x00) blue = 0x00; 

pixel = ((red & OxEO) | ((green & OxEO) >> 3) | ((blue & OxCO) >> 6)); 
return(pixel); 
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Freedom Series Graphics (S3150, S3250 and S3400) 
Device-Dependent Information 

This sections describes support for the Freedom Series on Hewlett-Packard 
workstations. 

Supported Visuals 

The following visuals are supported: 

■ Class Pseudocolor Depth 8 Layer Image: 
supports DBF and MBX hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image: 
supports DBF and MBX hardware double-buffering 

■ Class TrueColor Depth 24 Layer Image: 
supports DBF and MBX hardware double-buffering 

■ Class Pseudocolor Depth 8 Layer Overlay: 
supports DBF and MBX software double-buffering 

Supported Environment Variables 

No device-specihc environment variables are supported. 

GLX 

GLX is the OpenGL Extension to the X Window System. It is supported only 
on the Freedom Series Graphics Devices when attached to HP systems. 
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VRX Device-Dependent Information 

This section includes information on the PersonalVRX (PVRX) and TurboVRX 
(TVRX) graphics devices. 

Supported Visuals 

The following visuals are supported: 

■ Depth 3 (overlay and combined mode) 

■ Depth 4 (overlay and combined mode) 

■ Depth 8 (image and combined mode) 

■ Depth 12 (image and combined mode, TVRX only) 

■ Depth 16 (Creates a double-buffer version of the Depth 8 visual) 

■ Depth 24 (image and combined mode, TVRX only) 

None of these visuals support DBE and MBX double-buffering. 

In image mode the default visual is the Depth 8 PseudoColor visual. In overlay 
mode it is the depth 3 or depth 4 PseudoColor visual as specihed by the device 
hie. In combined mode the hrst device hie specihes the default visual. Examples 
are shown in the section below. 

VRX Device Files 

Different device hies exist for the image planes and overlay planes on VRX devices. 
The following table shows examples of device hies for VRX devices: 


Table 3-4. mknod Information for HP-UX 9.x 


Device Filename 

Major Number 

Minor Number 

Description 

/dev/crt 

12 

174 

Image mode 

/dev/ocrt 

12 

174 

Overlay mode (3 planes) 

/dev/o4crt 

12 

174 

Overlay mode (4 planes) 


The X server supports three different modes of operation on VRX devices: image, 
overlay and combined. 
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In image mode, the X server runs only in the image planes. This is the default on 
VRX devices. To operate in image mode, the image device hie should be specihed 
as the primary screen device. For example: 

/dev/crt # Image mode 

In overlay mode, the X server runs only in the overlay planes. Since only 3 or 4 
planes are available in the overlay planes on VRX devices, the number of colors 
is very limited. To operate in overlay mode, the overlay device hie should be 
specihed as the primary screen device. For example: 

/dev/ocrt # Overlay mode using 3 overlay planes 

or 

/dev/o4crt # Overlay mode using 4 overlay planes 

In combined mode, the X server runs in both image and overlay planes. To 
conhgure the X server to operate in combined mode, a primary and a secondary 
device must be specihed. The VRXSecondaryDevice is used for this purpose. For 
example: 


/dev/ocrt /dev/crt 

or 

/dev/crt /dev/ocrt 


# default visual lives 


in overlay planes 


# default visual lives 


in image planes 


X Windows, HP-UX 9.0r 3-39 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


FINAL TRIM SIZE : 7.5 in x 9.0 in 



X Windows: HP-UX 10.x 


This chapter documents information specihc to the HP X server. It describes 
features unique to HP’s X server, provides information on how to conhgure the 
X server and includes a list of supported X conhgurations. For each supported 
graphics device, device-dependent conhguration information is provided. 

Information specihc to a new release of the X server, beyond the scope of the 
general information in this document, can be found in the HP-UX Release Notes 
located in /usr/share/doc. 

If you prefer to read this information on paper, see the Graphics Administration 
Guide. It includes the same information as is contained here in this on-line 
document. 
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X Server Configuration 

Configuration of the X server is supported through SAM via an icon titled “X 
Server Configuration”. This icon resides either at SAM’s top level or under the 
top-level “Display” icon. This location is determined by the version of the HP- 
UX operating system (later HP-UX releases will place “X Server Configuration” 
under the “Display” folder). 

There are several X*screens files used to configure the operation of the X server. 
The SAM graphical user interface for X server configuration is provided to 
simplify complexity and facilitate ease of use. While it is still possible to modify 
these files manually (see below), using the SAM interface greatly simplifies the 
process for creating Multi-Display and Single Logical Screen configurations. 

Our SAM component has the following actions: 

Configure Print Server... 

Modify Multi-Screen Layout... 

Modify Server Options... 

Single Logical Screen (SLS) -> 


Describe Screen... 

Identify Screen 
Modify Default Visual... 

Modify Screen Options... 

Add Screen to Configuration 
Remove Screen from Configuration 

The first group of actions can be thought of as “global” actions. They will 
typically be active regardless of what has been selected. If any of these menu items 
is not visible, it is because it is not supported under the current configuration. 
For example, on systems containing only one graphics screen, the last three menu 
items will not be visible. 

The second group of actions can be thought of as “screen” actions. They will be 
activated depending on which screens have been chosen. It is also possible that 
the last two actions (Add and Remove) will be absent. When only one graphics 
screen is present, SAM will treat this screen as though it is always configured. 
Preselecting both configured and unconfigured screens will result in only the first 
two screen menu options being active. 
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X*screens File 

For manual changes, please refer to the sample hies in the /etc/Xll/ direc¬ 
tory. Three hies of particular interest are the XOscreens, XOdevices, and 
XOpointerkeys hies. 

Description of the XOscreens Configuration File 

This hie belongs in /etc/Xll/X*screens, where is the display number 
of the server. For example, the “XOscreens” hie is used when the $DISPLAY 
environment variable is set to {hostname) :0. {screen) and the server is invoked 
using the “:0” option. 

The X*screens hie is used to specify: 

■ Device-independent server options, and 

■ For each screen: 

□ What device hie to use (required), 

□ The default visual, 

□ Monitor size, and 

□ Device-dependent screen options. 

Note that all of the items above, except for device-independent server options, 
are specihed on a per-screen basis. 

The X server supports up to four screens at a time. Specifying more than four 
screens will cause a server error message. 

Syntax Guidelines 

■ Blank lines and comments (text following “#”) are ignored. 

■ Entries can occupy more than a single line. 

■ All symbols in the hie are recognized case-msensitive. 
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The x*screens File Format 


Items must appear in the X*screens file in the order that they are specified 
below. 

[ServerOptions 

[server _option) 

[server _option)] 

{Screen [device_name)'\ || 

{SingleLogicalScreen (ni?ou)s) [nCols) [device_namel) ... [device_nameN)'\ 
[DefaultVisual 

[Class [visual_class)] 

[Depth [depth)] 

[Layer [layer)] 

[Transparent]] 

[MonitorSize [diagonal_length) [units)] 

[MinimumMonitorPowerSaveLevel [level)] 

[ScreenOptions 

[screen_option) 

[screen_option)] 

Brackets (“[” and “]”) denote optional items. Italicized items in angle brackets 
(“(” and “)”) denote values to be specified. The double vertical line (“||”) denotes 
that one of the ored values (items surrounded by braces, “{” and “}”) must be 
included. 

The block from the “Screen [device_name)” line to the final “[screen_option)” 
line is referred to as a either a “Screen Entry” or as a “Single Logical Screen 
entry”. 

As shown above, the X*screens format is composed of an optional block 
specifying device-independent server options followed by one or more either 
Screen or Single Logical Screen entries (maximum of four graphics devices). 

The minimum X*screens file is a line with the keyword “Screen” followed by a 
screen device file. For example: 

Screen /dev/crt 
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Server Options 


For more information about server options, or about additional server options, 
look in an “info” file (for example, /usr/lib/Xll/Xserver/info/screens/hp). 

■ GraphicsSharedMemorySize {memory_size) 

Specify the size of the graphics shared memory region. The size must be spec- 
ihed in bytes and must be in hexadecimal. 

Default value: 0x580000 Environment Variables Replaced: GRM_SIZE, WMSHM- 
SPC. 

■ SMTSizes {size_spec) 

The size of the SMT regions (see the Shared Memory Transport section). 
Default value: 100000,90000,90000 

■ FileDescriptors {number) 

The number of hie descriptors available to the X server for its use. The number 
of connections (clients, more or less) is limited by the number of hie descriptors. 

The minimum value is 25, and a current maximum (as of HP-UX 10.20) of 
384, allowing a maximum of slightly under 256 total connections to the server. 
The default value is 192 (which allows a few under 128 connections). If a value 
provided is out of range, the server yields a warning and continues using the 
minimum or maximum, as appropriate. There is, however, a limit of 128 clients 
that can connect. 

The command line option -If {number) also specihes the value. 

■ ImmediateLoadDles 

The Xserver delays loading of some X extensions until the hrst protocol request 
to the given extension is received. Specifying this server option forces all 
extensions to be loaded at X server startup. Immediate loading of X extensions 
is the historical behavior of the HP-UX 10.10 and 10.20 X servers. 
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Screen Entries 


The minimum screen entry is a line with the keyword “Screen” followed by a 
screen device hie. 

Optional specihcations for default visual, monitor size, and device-dependent 
screen options may follow this minimal screen description line. 

■ DefaultVisual 

This optional part of the format specihes the default visual that the screen 
uses. Valid keywords following the “DefaultVisual” keyword are “Class”, 
“Depth”, “Layer”, and “Transparent”. 

If no default visual is specihed, then the standard default visual class, depth, 
layer, and transparency for the graphics device is used. 

Not all default visual specihcations will work on all devices. 

If there is an error in a specihcation, look in an information hie for more details 
(for example, /usr/lib/Xll/Xserver/info/screens/hp), in case it is newer 
than the document you’re now reading. 

□ Class [StaticGray) \ {GrayScale) \ [StaticColor) \ [PseudoColor) \ 
[TrueColor) \ [DirectColor) 

Specify the class of the default visual. 

□ Depth [depth_value) 

Specify the depth of the default visual (for example 8, 12, or 24). 

□ Layer [Image) \ [Overlay) 

Specify the layer of the default visual. 

□ Transparent\ Specify that a visual with an application-accessible transpar¬ 
ent entry in the default colormap be used. 

Specihcations in the “Def aultVisual” section, except for “Depth”, are ignored 
on VRX devices. See the “ScreenOptions” section below for VRX-related 
options. 

■ MonitorSize [diagonaPlength) Inches | MM 

Specify the diagonal size of the monitor. After the “MonitorSize” keyword, 
you must specify the diagonal length of the monitor and then the units. Use 
this entry only if you are using a non-standard monitor. 
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■ MinimumMonitorPowerSaveLevel [value) 

Specify the minimum power save level to be used by the monitor during screen 
blanking. You must specify a level of 0 —3. If the option is not used, the 
default is level 0. On devices that do not support DPMS, this option will be 
ignored. 

■ ScreenOptions 

Screen options are device-dependent options that are documented in a hie in 
the X server information directory (for example, 

/usr/lib/Xll/Xserver/info/screens/hp). 

Sample x*screens Files 

Below are several sample X*screens hies that illustrate the new format. 

■ This is the minimum legal X*screens hie, the “Screen” keyword followed by 
the screen device. Since no other information is given, the X server will assume 
default values for other options and settings. 

Screen /dev/crt 


(host) : 0.0 
/dev/crt 


Figure 4-1. Results of Minimal Legal x^screens File 
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■ This is the minimum specihcation for a two-screen conhguration. The 
maximum number of screens supported on the X server is four. Here, 
the displays associated with /dev/crtO and /dev/crtl are referred to as 
“(host):0.0” and “(host):0.1”, respectively. 

Screen /dev/crtO 
Screen /dev/crtl 


(host) : 0.0 


(host) : 0.0 

/dev/crtO 


/dev/crtl 


Figure 4-2. Two Physical Displays, Two Separate Screens 


■ This sample X*screens hie could be used on a system using Internal Color 
Graphics with a 17-inch monitor. In this example, the GraphicsSharedMemo- 
rySize is decreased to 1 Mbyte in order to reduce the swap space requirements 
of the system. Decreasing GraphicsSharedMemorySize is appropriate when 
you do not intend to run any 3D graphics applications. 

ServerOptions 

GraphicsSharedMemorySize 0x100000 
Screen /dev/crt 

MonitorSize 17 inches 

The display diagram would be the same as that of the “Results of Minimal 
Legal X*screens File” conhguration, above. 
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■ This sample X*screens file could be used on a system with a CRX24 graphics 
device. The overlay visual is selected as the default. There are 255 overlay 
colormap entries available on the CRX24. The 256th entry is hard-wired to 
transparent. Having less than 256 colormap entries should not cause a problem 
for most applications, but for those applications that require 256 colormap 
entries, the CountTransparentInOverlayVisual screen option should be used 
as shown below. Note that any attempts to modify the 256th entry will have 
no effect on the colormap. 

Screen /dev/crt 
ScreenOptions 

CountTransparentInOverlayVisual 

The display diagram would be the same as that of the “Results of Minimal 
Legal X*screens File” configuration, above. 

■ This sample X*screens file could be used on a system with a HCRX-24 graphics 
device. The default visual on the HCRX-24 is the opaque overlay visual. 
All 256 colormap entries are opaque and allocable. If an application requires 
transparency in the default visual, the “Transparent” keyword can be used to 
select the transparent overlay visual as shown below. 

Screen /dev/crt 
DefaultVisual 
Transparent 

The display diagram would be the same as that of the “Results of Minimal 
Legal X*screens File” configuration, above. 
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■ This sample X*screens file could be used on a system with a HCRX-8 
graphics device. By default on the HCRX-8, the overlay visual does not 
have a transparent entry available to applications for rendering transparency. 
If an application requires overlay transparency, an optional X server mode 
is available, but it is restrictive. In this optional mode, only one hardware 
colormap is available in the overlays (instead of two) and only one hardware 
colormap is available in the image planes (instead of two). The optional X 
server mode can be set via the EnableOverlayTransparency screen option as 
shown below. 

Screen /dev/crt 
ScreenOptions 

EnableOverlayTransparency 

The display diagram would be the same as that of the “Results of Minimal 
Legal X*screens File” configuration, above. 

■ This sample X*screens file could be used on a system using either a PVRX or 
TVRX graphics device. The server will run in combined mode with the default 
visual residing in the overlay planes. All visual depths which are supported by 
the graphics device will be available. 

Screen /dev/ocrt 
ScreenOptions 

VRXSecondaryDevice /dev/crt 


(host) : 0.0 
/dev/crt 
/dev/ocrt 

Figure 4-3. PVRX/TVRX Display with Overlays 
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■ This sample X*screens file could also be used on a system using PVRX or 
TVRX graphics. The server will run in combined mode with the default visual 
in the overlay planes and an 8/8 double-buffered visual in the image planes. 
In general, specify VRXDoubleBuff er if applications will be using DHA (Direct 
Hardware Access) double-buffer functionality (e.g., Starbase double buffering). 

Screen /dev/ocrt 
ScreenOptions 

VRXSecondaryDevice /dev/crt 
VRXDepth 16 

VRXDoubleBuffer 

The display diagram would be the same as that of the “PVRX/TVRX Display 
with Overlays” configuration, above. 

■ These sample X*screens file entries could be used on a system with two 
homogeneous graphics devices. Assuming the first device is associated with 
the device file “/dev/crtO” and the second device is associated with the device 
file “/dev/crtl”, both examples specify a horizontal Single Logical Screen 
configuration. 

SingleLogicalScreen 1 2 
/dev/crtO /dev/crtl 

or 

SingleLogicalScreen 1 2 
/dev/crtO 
/dev/crtl 


(host) : 0.0 

/dev/crtO /dev/ocrt 


Figure 4-4. Two Physical Displays, Single Logical Screen (1x2) 
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■ These sample X*screens entries could be used on a system with four 
homogeneous graphics devices. Assuming the hrst device is associated with 
the device hie “/dev/crtO”, the second device is associated with the device hie 
“/dev/crtl”, etc. The following examples specify valid Single Logical Screen 
conhgurations. 

□ SingleLogicalScreen 1 4 

/dev/crtO /dev/crtl /dev/crt2 /dev/crt3 


I- (host) : 0.0-1 

/dev/crtO /dev/crtl /dev/crt2 /dev/crt3 


Figure 4-5. Four Physical Displays, Single Logical Screen (1x4) 
4 
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□ SingleLogicalScreen 4 1 
/dev/crtO 
/dev/crtl 
/dev/crt2 
/dev/crt3 


(ho 

i 

\ 

st) : 0.0 

^/dev/crtO 

/dev/crtl 

/dev/crt2 

/dev/crt3 

r 


Figure 4-6. Four Physical Displays, Single Logical Screen (4x1) 
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□ SingleLogicalScreen 2 2 
/dev/crtO /dev/crtl 
/dev/crt2 /dev/crt3 




^ /T. n-f- 1 . r\ r\ 


{tl/OStJ . U . U 

/dev/crt0 

/dev/crtl 

_! 

/dev/crt2 

r 

/dev/crt3 


Figure 4-7. Four Physical Displays, Single Logical Screen (2x2) 


■ It is possible to include a Screen Entry and an SLS Screen Entry in the same 
X*screens Eile. This creates a situation where there are two X Screens (e.g. 
{host ): 0.0 and {host ): 1.0), one of which happens to be a Single Logical Screen. 
Below is an example of this: 


Screen /dev/crtO 
SingleLogicalScreen 1 2 
/dev/crtl /dev/crt2 


(host) : 0.0 


(host) : 1.0 

/dev/crtO 


/dev/crtl /dev/crt2 


Figure 4-8. Three Physical Displays, Screen plus Single Logical Screen (1x2) 
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Miscellaneous Topics 


Double Buffer Extension (DBE) 

DBE is an extension to the X server that provides a double-buffering Application 
Programming Interface (API). Note that MBX (the Multi-Buffering extension 
to X) has not been adopted as an industry standard, as DBE has. Thus, it 
is recommended that applications that use MBX be ported to DBE usage in 
preparation for future MBX obsolescence (HP-UX 11.0). Eor more information 
about DBE and the API, consult the DBE man pages: 

DBE 

XdbeQueryExtension 
XdbeGetVisualInfo 
XdbeFreeVisualInfo 
XdbeAllocateBackBufferName 
XdbeDeallocateBackBufferName 
XdbeSwapBuffers 
XdbeBeginIdiom 
XdbeEndIdiom 

XdbeGetBackBufferAttributes 

Performing Buffer Swaps On Vertical Blank 

Eor performance reasons, the default DBE behavior is to not synchronize buffer 
swaps with the monitor’s vertical retrace period. In some instances, therefore, 
image tearing (seeing part of the old image and part of the new image on the 
display at the same time) could be visible while swapping large DBE windows. 
Eor those instances where tearing would occur and is undesirable, an optional X 
server mode is available to allow for synchronization of buffer swaps with vertical 
retrace. To activate this optional X server mode, set the following screen option 
in the X*screens Eile before the X server is started: 

SwapBuffersOnVBlank 

Note that MBX_SWAP_BUFFERS_OI_VBLAIK is obsolete with this release. The 
SwapBuff ersOnVBlank Screen Option works for both DBE and MBX. 
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Determining Swap Performance 


The DBE API does not allow users to determine if double-buffering in a 
visual is through software or hardware. However, the API does provide a 
way to determine relative swapping performance on a per-visual basis. The 
XdbeScreenVisualInfoO function returns information about the swapping 
performance levels for the double-buffering visuals on a display. A visual 
with a higher performance level is likely to have better double-buffer graphics 
performance than a visual with a lower performance level. Nothing can be 
deduced from any of the following: the magnitude of the difference of two 
performance levels, a performance level in isolation, or comparing performance 
levels from different servers. 

For more information, refer to the DBE man page on XdbeScreenVisualInfoO. 

Supported Devices 

The X server supports DBE on the following devices: 

■ Internal Color Graphics 

■ Integrated Color Graphics 

■ CRX-24[Z] 

■ CRX-48Z 

■ HCRX-8[Z] 

■ HCRX-24[Z] 

■ HP Visualize™ -EG 

■ HP Visualize-8 

■ HP Visualize-24 

■ HP Visualize-48[XP] 

■ HP Visualize-FX^ 

■ HP Visualize-FX'^ 

■ HP Visualize-FX® 

■ Freedom Series^'^ Graphics (S3150, S3250 and S3400) 
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Display Power Management Signaling (DPMS) 

Monitors constitute a large percentage of the power used by a workstation even 
when not actively in use (i.e., during screen blanking). In order to reduce the 
power consumption, the Video Electronic Standards Association (VESA) has 
dehned a Display Power Management Signaling (DPMS) standard which can be 
used to greatly reduce the amount of power being used by a monitor during screen 
blanking. 

The X server features the ability to make use of DPMS on the following graphics 
devices: 

■ HP Visualize-EG 

■ HCRX-8[Z], HCRX-24[Z] 

■ HP Visualize-8, HP Visualize- 24, and HP Visualize-48[XP]. 

■ HP Visualize-EX^, HP Visualize-EX'^, HP Visualize-EX® 

The following table is a description of the states that are dehned by VESA. The 
Power Savings column indicates (roughly) the level of power savings achieved in 
the given state. The Recovery Time is the amount of time that the screen takes 
to return to a usable state when the screen saver is turned off (by pressing a key 
or the moving the mouse). 


Table 4-1. Power-Saving States Defined by VESA 


Level 

State 

DPMS Compliance 
Requirements 

Power Savings 

Recovery Time 

0 

Screen Saver 

Not Applicable 

None 

Very Short (<1 sec) 

1 

Stand-by 

Optional 

Minimal 

Short 

2 

Suspend 

Mandatory 

Substantial 

Longer 

3 

Off 

Mandatory 

Maximum 

System Dependent 


The actual amount of power saved and the recovery time for each of the states is 
monitor-dependent and may vary widely. The customer can compensate for this 
by choosing an appropriate level for the monitor that is currently in use. 
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By default, the DBMS level used is the Screen Saver (i.e. no power savings). If 
you wish to use power saving during screen blanking, set the following X*screens 
hie entry before starting the server: 

MinimumMonitorPowerSaveLevel [level) 

where [level) is replaced with the single digit 0, 1, 2, or 3 as specihed in the Level 
column in the above table. 

MBX 

The MBX extension (Multi-Buffering Extension) is supported on all graphics 
devices supported on the HP 9000/700 machines, except the PersonalVRX and 
the TurboVRX. 

HP’s implementation of MBX exists mainly to support fast double-buffering for 
PEX applications. Therefore, MBX only supports allocation of one or two MBX 
buffers; no more. Some graphics devices/visuals have a single 8-plane buffer; 
this includes the color graphics device and the overlay planes on the CRX-24[Z], 
CRX-48Z, HCRX, and HP Visualize family. Eor these devices, MBX double¬ 
buffering is still supported, but the second bank is allocated in virtual memory. 
Rendering and buffer-swapping in these instances is slower than devices/visuals 
that support true hardware double-buffering. 

There is no easy way to determine which visuals, from a device’s list of visuals, 
support fast MBX hardware double-buffering. The CRX and Dual-CRX device 
is a double-buffered device and therefore always supports MBX hardware double¬ 
buffering. The Internal Color Graphics, Integrated Color Graphics or Color 
Graphics card devices only support MBX software buffering. All other devices 
that have both overlay and image planes support fast MBX hardware double¬ 
buffering in the image planes and slower MBX software double-buffering in the 
overlays. Consult the following device-specihc sections for a list of visuals that 
support software and hardware MBX double-buffering. 

Eor performance reasons, the default MBX behavior is to not synchronize with 
the monitors vertical retrace period. In some instances, image tearing could be 
visible while swapping large MBX windows. Eor those instances where tearing 
would occur and is undesirable, an optional X server mode is available to allow for 
synchronization with vertical retrace. To activate this optional X server mode, 
set the SwapBuff ersOnVBlank Screen Option in the X*screens hie before the X 
server is started. 

4-18 X Windows: HP-UX lO.r 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


Note that MBX_SWAP_BUFFERS_OI_VBLAIK is obsolete with this release. The 
SwapBuff ersOnVBlank Screen Option works for both DBE and MBX. 

With this mode enabled, all MBX buffer swaps are synchronized with the 
monitor’s vertical retrace period. 

This mode is not needed in drawables used for BEX rendering. PEX turns 
synchronization on and thus does not require this tuning. 

The MBX Application Programming Interface is thoroughly discussed in the 
PEXlib Programming Manual by Tom Gaskins, and published by O’Reilly & 
Associates, Inc. Consult that manual to understand the creation, manipulation, 
and destruction of MBX buffers. 

Since MBX is not an industry standard, and will be discontinued on HP-UX 11.0, 
developers should replace MBX calls with the appropriate DBE calls. 


Note 



Note that XmbufGetScreenInfoO can indicate that a window 
supports MBX even if only one MBX buffer is supported. An 
application should always check the max_buffers held in the 
returned XmbufBufferinfo structure before assuming that a 
window supports two MBX buffers. 


Shared Memory Extension (mit_shm) 

The MIT shared memory extension provides both shared-memory Xlmages and 
shared-memory pixmaps based on the SYSV shared memory primitives. 

Shared memory Xlmages are essentially a version of the Xlmage interface where 
the actual image data is stored in a shared memory segment, and thus need not be 
moved through the Xlib interprocess communication channel. Eor large images, 
use of this facility can result in increased performance. 

Shared memory pixmaps are a similar concept implemented for the pixmap 
interface. Shared memory pixmaps are two-dimensional arrays of pixels in a 
format specihed by the X server, where the pixmap data is stored in the shared 
memory segment. In all other respects, shared memory pixmaps behave the same 
as ordinary pixmaps and can be modihed by the usual Xlib routines. In addition, 
it is possible to change the contents of these pixmaps directly without the use of 
Xlib routines merely by modifying the pixmap data. 
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Supported Devices 

The X server supports the MIT shared memory extension on the following devices: 

■ Internal Color Graphics 

■ Integrated Color Graphics 

■ CRX-24[Z] 

■ CRX-48Z 

■ HCRX-8[Z] 

■ HCRX-24[Z] 

■ HP Visualize-EG 

■ HP Visualize-8 

■ HP Visualize-24 

■ HP Visualize-48[XP] 

■ HP Visualize-FX^ 

■ HP Visualize-FX'^ 

■ HP Visualize-FX® 

Shared Memory Transport (SMT) 

Shared Memory Transport (SMT) is a means to more rapidly transport large 
amounts of data from the client to the server. It is distinct from the MIT Shared 
Memory Extension, which is specihcally for various types of images, although 
SMT can be used with that extension. 

SMT is particulary advantageous for operations that move large amounts of data 
in a single request, such as a polyline or a polypoint, and for images when the 
MIT Shared Memory Extension is not used. It will work with the Big Requests 
Extension, but whether it will exhibit a performance increase depends on the 
size of the actual extended size request. There are some X requests for which no 
improvement is expected. 

SMT is the default transport for 10.20 whenever a display name of any of the 
forms listed below are used, and when the client and server are actually on the 
same host. Note that “:0.0” is used for simplicity. This behavior is equally 
applicable for displays such as etc. 

■ : 0.0 

■ local:0.0 

■ {hostname ): 0.0 

■ shmlink:0.0 
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A display name of the form unixrO.O will force the use of Unix Domain Sockets 
(UDS), which is identical to the local transport used before HP-UX 10.20. 

A display name of the form nn . nn. nn . nn :0.0 (where nn .nn .nn. nn is an IP 
address) will force the use of Internet Sockets, which is the remote transport 
normally used, and which can be used locally. (This will be slow.) 

It is possible that an application which violates the X interface standard will run 
correctly using UDS but hang or coredump when using SMT. Users encountering 
this problem can use: 

DISPLAY=unix : 0 {command_and_args) 

to run the application compatibly, but without the performance improvement of 
SMT. 

Note that if neither SMT nor UDS are desired, setting XFORCE_INTERNET=True 
before starting the X server forces all protocol to interact directly with the 
hardware internet card. 

SMT uses hie space on the hie system containing /var/spool/sockets/Xll. 
Should it be the case that that hie system is full, the X server will use Unix 
Domain Sockets (UDS) but print a warning (in /var/vue/Xerrors if VUE is in 
use or /var/dt/Xerrors CDE is in use) on each connection startup. To address 
this (and if space cannot be made), /var/spool/sockets/Xll can be a symbolic 
link to another hie system with more space. If /var/spool/sockets/Xll is on a 
NTS hie system, currently SMT will (silently) not start, and the connection will 
be made using Unix Domain Sockets. Again, a symbolic link to a conventional 
hie system may be used to deal with this. 
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Performance Tuning of SMT 

The default values of some buffer sizes have been tuned for optimal performance 
in most situations. However, these are not necessarily optimal in all conditions. 
Under some circumstances system performance might be optimized (possibly 
at the expense of X performance) by tuning these parameters. Under most 
circumstances this should be unnecessary. 

The Server accepts these parameters via the X*screens hie, in the ServerOp- 
tions section. In this case, the default for all SMT connections is set. 

The client accepts these parameters via the environment variable X_SMT_SIZES. 
For the client, the value affects all client connections to the server made while 
this environment variable is set. 

In either case, the format and meaning of the helds is the same: 

{region_size)[, {high_water) [, {bujfer_size)]] 

with no embedded blanks. For example: 

32000,16000,5000 

32000 

0 

The default is 100000,90000,90000. 

The values are accepted as positive decimal, hex, or octal values according to the 
C conventions. 
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The special value of 0 (for buffer size; all other values are ignored) indicates that 
SMT is to be suppressed. 

{region_size) controls the amount of shared memory allocated for the transport 
(in bytes). This has the largest effect on system performance. 
The value is rounded up to the next page boundary. Larger 
values yield faster X performance but there is a point of 
diminishing returns. The default is 100000 (which is rounded 
to 0x19000). 

{high_water) is a soft boundary which affects the load on the Virtual Memory 
system. The value is rounded up to the next page boundary. 
The smaller the value, the smaller the number of pages actually 
used while sending “normal, small” X messages. Large messages 
can still be sent at high efficiency. In a memory-poor system 
making this small may be an advantage, but if sufficient memory 
is available, the value should be near the default. 

The default value for {high_water) is 90000 or, if {region_size) 
is given, 1/8 of the region size (which is appropriate in memory- 
poor systems), with a minimum of 4096. If {high_water) is 
specihed (and if {region_size) is specihed, {high_water) usually 
should be also) it must be less than the {region_size). 

{bujfer_size) is the size used for the “small” requests that X normally generates 
protocol for. It is extremely unlikely that this will need tuning. 
It is not rounded. It must be at least 4096, but defaults to the 
same as the {high_water) size (if the option is used). Space is 
left for a control region if necessary. 

The {high_water) value must ht within the region (and should be smaller), the 
buffer must ht within the high-water mark (and consequently the buffer must ht 
within the whole region). 

If these parameters are used, be sure to conhrm that they actually cause 
an improvement in actual usage situations. Incorrect values can degrade 
performance. 
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Not6 Begin Note for Programmers 

y^l X Applications which call fork(), and access the same display 

TP structure from both the parent and the child cannot be expected 

to operate reliably without extreme care (if at all), whether or 
not SMT is used. However, SMT is more sensitive to this than 
UDS. The problem is quite similar to stdio, where fflushO 
must be used to assure that data makes it from the buffer onto 
the hie exactly once. 

Similarly to stdio ’s use of fflushO , XFlushO (not _XFlush()) 
must be called immediately before any forkO call that will be 
accessing the display from both the parent and child, as well as 
any time control is transferred between the parent and child, or 
vice-versa. (Calls to forkO which immediately do an execO 
4 are not a problem.) 

The SMT library code attempts to detect improper use of 
display connections after a fork, and issues a warning at runtime. 
However, not all all such usages can be detected. Symptoms 
include reporting the error, and applications hanging. 

Also, because the parent and child might read from the same 
display connection (either replies or events) the library can detect 
inconsistent sequence numbers, which it will report. It will 
attempt to recover from such errors, but depending on what the 
application has done, recovery cannot always be successful. 

Only for R5 Applications 

SMT requires a change to an internal interface with the X library. 
In theory, no application should be calling this interface, but some 
applications, including at least one X test suite, are known to 
call it. The interface is _XConnectDisplay. Applications using 
it directly may not be able to use SMT for the display specihed, 
and must add an extra (ninth) parameter, which is the address 
of an integer: 

int dummy; 

_XConnectDisplay(... , fedummy); 
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Symptoms include both damaged data and core dumps. 

(There was an earlier HP Shared Memory Transport, which this 
one replaces. It used the same parameter, so it may be the case 
that any such calls have already been hxed.) 

This problem does not occur in the R6 library. 

End Note for Programmers 


HP Color Recovery 

Color Recovery is a technique that generates a better picture by eliminating the 
graininess caused by traditional dithering techniques. It is available on these 
graphics devices: 

■ Integrated Color Graphics and plug-in Color Graphics cards 

■ HP Visualize-EG 

■ HCRX-8[Z], HCRX-24[Z] 

■ HP Visualize-8, HP Visualize- 24, and HP Visualize-48[XP] 

■ HP Visualize-FX^, HP Visualize-FX'^, and HP Visualize-FX® 

Color Recovery is available when using either depth-8 PseudoColor or depth-8 
TrueColor visuals. 

There are two components to the Color Recovery process. First, a different 
dither-cell size (16x2) is used when rendering shaded polygons. Second, a digital 
hlter is used when displaying the contents of the frame buffer to the screen. 

Under some conditions. Color Recovery can produce undesirable artifacts in the 
image (this also happens with dithering, but the artifacts are different). However, 
images rendered with Color Recovery are seldom worse than what dithering 
produces. In most cases. Color Recovery produces signihcantly better pictures 
than dithering. 

Color Recovery is available by default for all depth-8 color visuals on devices that 
support the feature. If, for some reason, you wish to disable Color Recovery, set 
the DisableColorRecovery Screen Option in the X*screens hie before starting 
the server (note that this disables Color Recovery for 3D APIs as well). 

Color Recovery is enabled in conjunction with a particular X colormap that is 
associated with your window. If the X colormap is not installed in hardware, 

X Windows: HP-UX 10.r 4-25 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


you may not see the effect of the Color Recovery hlter (you may not even see the 
correct colors for that window). Given that more than one hardware colormap 
(or “color lookup table”) is available, this should happen infrequently. 

The Color Recovery colormap is a read-only colormap. Any attempts to change 
it will be ignored and no error will be reported. 

Access to the Color Recovery capability is transparent when using a 3D graphics 
API such as Starbase, HP-PHIGS or PEX. If you are producing graphics using 
Xlib calls, your application must perform some of the necessary processing. 
The method to access Color Recovery via Xlib is described in a section called 
“Accessing HP Color Recovery Technology via Xlib” in the device-dependent 
sections. 

Dynamic Loading 

HP’s X server now dynamically loads the appropriate device drivers and 
extensions based on the target graphics display device and the extensions the 
device driver supports. This feature should be transparent to X server users. 

When possible, the loading of X extensions is deferred until the hrst protocol 
request is encountered for a given extension. This feature should be transparent to 
X server users; however, it is expected to provide some performance enhancement. 

Dynamically loaded modules are recorded by the X server in the hies 
“/var/Xll/Xserver/logs/X*.log”, where the of X*.log rehects the display 
identiher for that given run. Only that last invocation against a given display 
identiher is retained. The log hie contains the parsed contents of the given 
X*screens hie and the full path name for all dynamically loaded modules for 
the given X server invocation. Deferred loaded modules are recorded as they are 
referenced. 


Note 



Altering or removing hies under /usr/lib/Xll/Xserver may 
prevent the X server from running. 


4-26 X Windows: HP-UX 10.r 


FINAL TRIM SIZE 


7.5 in X 9.0 in 


Include Inferiors Fix 


When a client application creates an X Graphics Context (GC), it is possible to 
specify the subWindowMode component. The two possible values are ClipByChil- 
dren (default) and Includeinf eriors. If the GC specihes ClipByChildren, any 
rendering to a window with inferior windows (i.e., the child is wholly enclosed 
by the parent) will appear only in the destination window. In other words, the 
rendering will not take place inside the inferiors. If the GC specihes Includeln- 
f eriors, and the same rendering request is made, it is the responsibility of the X 
Server to ensure that the rendering is not clipped from the inferior windows. In 
other words, the rendering will appear in the destination window and the inferior 
windows. 

With the advent of multi-layer devices, the Includeinf eriors mode became 
defective. Depending upon which layer or hardware buffer the destination 
drawable and inferior windows were in, the rendering may or may not have taken 
place. Also, the Getimage protocol clearly specihes that the default Getimage 
behavior is to include the depth-dependant contents of inferior windows (in other 
words, Getimage requires that Includeinf eriors work properly). 

As of the 10.10 release, HP has offered a solution to the Includeinf eriors 
defect. Some customers create their test image archives using XGetImage (which 
currently returns incorrect data for multi-layer and double-buffered devices). 
Therefore, the Include Inferiors Fix will not be enabled by default. To enable 
the Include Inferiors Fix, add the EnableincludeinferiorsFix Screen Option 
to the X*screens hie. 

For example: 

Screen /dev/crt/ 

ScreenOptions 

EnableincludeinferiorsFix 

This gives a system administrator control over when the hx is active and when it 
is not. In this way, each site can evaluate whether or not it is benehcial to enable 
this hx. 
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Shared Memory Usage With 3D Graphics 

Graphics processes use shared memory to access data pertaining to the display 
device and Xll resources created by the server. (“Resources” includes windows, 
colormaps, and cursors.) The Xll server initiates an independent process 
called the Graphics Resource Manager (GRM) to manage these resources among 
graphics processes. Graphics processes include PEXlib, PHIGS, and Starbase 
applications. One problem encountered with GRM shared memory is that it may 
not be large enough to run some applications. 

Graphics applications that require VM double-buffering use large amounts of 
shared memory. Shared memory can be completely consumed by several double- 
buffered graphics windows. When an application attempts to use more shared 
memory than is available, the application encounters errors and might terminate. 

You can circumvent the problem by using Server Options to change the shared 
memory size. 

Changing Graphics Shared Memory Size 

The size of the shared memory segment used by the GRM can be controlled 
through a Server Option. The default value is 0x580000 (5.5 Mbytes) on Series 
700 computers. 


Note 



The actual GRM shared memory size on a system can be 
determined by running “ipcs -ma”, Ending the entry with CPID 
matching the process ID of the grmd process and then checking 
the segment size (SEGSZ) held. 


If more shared memory space is needed, graphics shared memory size can be 
increased. For example, to set it to eight megabytes: 

ServerOptions 

GraphicsSharedMemorySize=0x800000 

Note that the value must be in hexadecimal. The new value won’t take effect 
until you restart the X Server. 

It is also possible to decrease the size of GRM shared memory. You may want to 
do this if you want to reduce the swap-space requirements of your system and/or 
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you do not intend to run any 3D graphics processes. For example, you could 
reduce graphics shared memory size to 0x100000 (one megabyte). 

Count Transparent In Overlay Visual 

In some conhgurations, an 8-plane overlay visual may have less than 256 colors. 
This should not cause a problem for most applications. If an application depends 
on 8-plane visuals having 256 colormap entries, this option may be useful. Setting 
this option will cause the X server to count transparent entries in the number of 
colormap entries. 

■ Examples of Relevant Graphics Devices: 

□ CRX-24[Z], CRX-48Z 

□ HP Visualize-EG 

□ HCRX-8[Z], HCRX-24[Z] 

□ HP Visualize-8, HP Visualize-24, and 

□ HP Visualize-48[XP] 

□ HP Visualize-FX^, HP Visualize-FX'^, and HP Visualize-FX® 

■ X*screens File Screen Option To Use: 

CountTransparentInOverlayVisual 

Enable Overlay Transparency 

This option is used to enable the usage of an overlay transparent color on devices 
that can support it, but, by default, do not allow it (for example, HCRX-8). 

■ Examples of Relevant Graphics Devices: 

HP Visualize-EG HCRX-8[Z] HP Visualize-8 

■ X*screens File Screen Option To Use: 

EnableOverlayTransparency 
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3-Bit Center Color 


This option is available to force the X server to center colors in the colormap 
to values that will reduce the amount of twinkle on flat-panel conversion. This 
option applies only to flat-panel displays. 

The twinkling effect is caused by the analog-to-digital conversion. Due to noise 
in the analog signal, it is possible for a color near a boundary between two digital 
values to cause the conversion to bounce back-and-forth between the two colors 
(i.e., “twinkle”). In order to avoid this effect, the server “centers” the colors as 
far from the color boundaries as possible. 

■ Examples of Relevant Graphics Device: 

Integrated Color Graphics, Color Graphics cards. Internal Color Graphics 

■ X*screens File Screen Option To Use: 

3BitCenterColor 

Image Text Via BitMap 

When using the Xlib XDrawImageStringO call to draw text, a visual effect may 
be seen where text appears to flicker as the background and foreground are drawn 
in distinct graphics operations. This option is available to eliminate the flicker 
effect but at the expense of reduced text performance. The option will make 
the X server hrst draw text to an off-screen pixmap prior to displaying it to the 
screen. 

X*screens File Screen ImageTextViaBitMap 

Option To Use: 


Note 



Using this option will reduce text performance. 


The ImageTextViaBitMap screen option is supported on all graphics devices 
supported on the HP 9000/700 machines, except the following: 

■ PersonalVRX, TurboVRX 

■ Freedom Series™ Graphics (S3150, S3250 and S3400) 
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Obsolete Environment Variables 

These HP-UX 9.x environment variables are no longer supported: 

HP_SUPPRESS_TRUECOLOR_VISUAL 

HP_COLORMAP_MAIAGEMEIT_SCHEME 

WMSHMSPC 

MBX_SWAP_BUFFERS_OI_VBLAIK 

CRX24_C0UIT_TRAISPAREIT_II_0VERLAY_VISUAL 

Special Device Files 

Special device files are used to communicate between the computer and peripheral 
devices. The X server requires the use of a special device file for each graphics 
card present in the system. On HP-UX 10.a; systems, five special graphics device 
files are automatically created. The first or primary graphics card, also known 4 
as the “console”, uses the “/dev/crt” or “/dev/crtO” device file. The others 
are called “crtl”, “crt2”, and “crt3” and also reside in “/dev”. Those systems 
containing multiple graphics devices on a single card (Dual Color Graphics and 
Dual CRX, for example) need to have special device files manually created for 
them. 

Special device files are created by using SAM (the System Administration 
Manager tool): 

1. From SAM’s main window, double-click “Peripheral Devices”. 

2. From the “Peripheral Devices” window, double-click “Cards”. 

3. A window will appear, containing a list of all cards that are in your machine. 

Once you select any of them (by single-clicking), the “Actions” menu will 
contain the options “Show Device Files” and “Create Device Files.” Choose 
whichever option you desire. 
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Supported X Configurations 


Multi-Display Support 

The following definitions are included to reduce confusion between the terms 

“multi-display,” “multi-screen,” “multi-seat,” and “single logical screen.” 

Multi-Display A configuration with multiple graphics devices used 

concurrently. Any multi-screen, multi-seat, or single 
logical screen configuration is referred to as a multi¬ 
display configuration. 

Multi-Screen A configuration in which a single X server with a mouse 

and keyboard drives multiple graphics devices (where 
each display is a different X Screen) concurrently while 
only allowing the cursor, not windows, to be moved 
between displays. 
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Multi-Seat A configuration with multiple instantiations of the X 

server, each with its own mouse, keyboard, and dis- 
play(s). Multi-seat is not supported in any HP-UX 10.* 
release. 



Keyboard 1 Mouse 1 Keyboard 2 Mouse 2 

Figure 4-10. 
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Single Logical Screen A configuration in which a single X server with a 

single mouse and keyboard drives multiple homogeneous 
graphics devices concurrently while allowing the displays 
to emulate a large single screen. This differs from a multi¬ 
screen environment by allowing windows to be moved 
and displayed across displays. See the section in this 
document on Single Logical Screen. 


host:0.0 

(2560x1024) 



Note that different monitor resolutions are not supported 
with the multi-display configurations unless stated oth¬ 
erwise in the table below. 
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Multi-Screen Support 

The list of supported multi-display configurations is rather large, and it changes 
whenever a new graphics device is introduced. Thus, if you are considering a 
Single Logical Screen or any other multi-display conhguration, we recommend 
consulting your HP Sales Representative and inquiring whether the conhguration 
you have in mind is indeed supported. 

There are general guidelines, however. For example: 

■ Multi-display conhgurations may be limited by available power. Depending on 
the capacity of your computer’s power supply, and the power demands of the 
combination of graphics cards you are considering, there may or may not be 
enough power to operate them all. 

■ Single Logical Screen conhgurations must use identical graphics devices (see 
the next section). 

Single Logical Screen (SLS) 

SLS is a mechanism for treating homogeneous multi-display conhgurations as 
a single “logical” screen. This allows the moving/spanning of windows across 
multiple physical monitors. The word “homogeneous” is included because SLS 
only works if the graphics devices included in the SLS Conhguration are of the 
same type. Note that on-board and “card” versions of the same device can be 
considered identical; for example, you could use an on-board HP VISUALIZE-EG 
graphics device and an HP VisUALiZE-EG graphics card, and still consider them 
identical devices, thus permitting a 1x2 SLS or a 2x1 SLS. 
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SLS is enabled by using SAM (the System Administration Manager tool, 
/usr/sbin/sam). To enable an SLS configuration, start SAM, and follow the 
instructions below: 

■ Double-click on the “X Server Configuration” button. A window entitled 
“Graphics” appears, containing an icon for every graphics device on your 
system. 

■ Select the devices you want to combine into an SLS (click the mouse on the 
first device, and [Ctrl]-click on the others). At this point, all the devices you 
want to combine into an SLS configuration should be highlighted. 

■ From the “Actions” menu, choose the menu item “Modify Multi-Screen 
Layout”. A dialog box appears, allowing you to specify exactly how you want 
your SLS configuration to be. 

Note that if your machine has only one graphics device, the “Modify Multi-Screen 
Layout” menu option does not even appear, since multiple devices cannot occur 
in a single-device context. 

Note also that DHA (Direct Hardware Access) is not supported in a window 
that spans multiple screens. This means, for example, that while graphics is 
supported to a window spanning two or more screens, accelerated graphics is not. 
“Spanning,” in this context, includes a window that is two or more screens in 
size, as well as a window that is partially on one screen and partially on another 
(even though it would fit on a single screen if it were moved). 

SLS can also be enabled via the /etc/Xll/X*screens file via the syntax: 

SingleLogicalScreen n m 

/dev/crtO ... /dev/crtfc 

where: n = the number of “rows” in the physical configuration, m = the number 
of “columns” in the physical configuration, and the product of nx m is 
less than or equal to four. 

For example, to create a logical screen that is one monitor tall by two monitors 
wide, the following syntax would be used: 

SingleLogicalScreen 1 2 
/dev/crtO /dev/crtl 
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Whereas for a logical screen that is two monitors tall by one monitor wide, the 
syntax is: 

SingleLogicalScreen 2 1 
/dev/crtO /dev/crtl 

3D Acceleration and Single Logical Screen 

Currently, SLS does not take advantage of 3D acceleration (e.g. CRX-24Z). 3D 
applications (from any supported HP 3D API) will continue to run with SLS; 
However, 3D performance with SLS will be much slower than it is without SLS. 

HP VUE/CDE and Single Logical Screen 

Please note that HP VUE/CDE has not been modihed to take advantage of the 
Single Logical Screen capability. When presenting information on your display, 
HP VUE may split a window across physical screens. Examples include: 

■ The login screen. 

■ The Eront Panel. 

■ Window move and resize boxes. 

■ The screen lock dialog. 

This behavior is the result of HP VUE’s naive assumption that it is running 
against one large screen; it centers these windows accordingly. 

If you are using the default HP VUE key bindings, you can easily reposition the 
Eront Panel so that it is completely contained within one physical screen: 

1. With the input focus on the Eront Panel, press fAit~) [Space] (on older keyboards, 
use f Extend Char ] f Space ] ). 

2. With the Eront Panel menu posted and the “Move” menu item selected, press 
f Enter ] (ou older keyboards, f Retum ] ) to start the move. 

3. Use the mouse or the arrow keys to reposition the Eront Panel to the desired 
location. 

4. Press f Enter] (or f Return ] ) to Complete the move. You may instead press f isT) to 
cancel the move. 

Afterwards, this setting will be remembered and restored at your next login. If 
you have previously set a Home session, you will need to re-set the Home session 
in the Style Manager to register the new Eront Panel position. 
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Note that there is no mechanism in HP VUE for repositioning the login screen, 
window move/resize boxes, or the screen lock dialog. 


4 


4-38 X Windows: HP-UX 10.r 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


Integrated Color Graphics Device-Dependent Information 

This sections includes information on Integrated Color Graphics and Color 
Graphics cards. 

Supported Visuals 

For color displays: 

■ Class PseudoColor Depth 8 - 

supports DBF and MBX software double-buffering 

■ Class TrueColor Depth 8 - 

supports DBF and MBX software double-buffering 

For grayscale displays, only one visual is supported: 

■ Class Grayscale Depth 8 - 4 

supports DBF and MBX software double-buffering 

Supported Screen Options 

The following Screen Options are supported: 

■ DisableColorRecovery 

■ 3BitCenterColor 

■ ImageTextViaBitMap 

Colormaps and Colormap Management 

Color Graphics devices have two hardware colormaps (color lookup tables), each 
with 256 entries. The X server controls the allocation and contents of these 
hardware colormaps. 
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Default Colormap Management Scheme 

Many applications use the default Xll colormap. A technicolor effect in the 
windows using the default colormap occurs when a non-default colormap is 
downloaded in the hardware colormap that had previously contained the default 
colormap. 

Because so many applications use the default Xll colormap—including the 
window manager—and because Color Graphics devices have two hardware 
colormaps, the default behavior on this device is to dedicate one hardware 
colormap to always hold the default Xll colormap. The second hardware 
colormap is available to applications that use colormaps other than the default. 

The default behavior can cause technicolor if two or more applications are using 
different, non-default colormaps. For example, Application A uses the default 
Xll colormap. Application B uses a different colormap, and Application C uses 
a third colormap. If applications A, B, and C are all executed simultaneously on 
a Model 712, application A would look correct. Either application B or C would 
have a technicolor effect—the application whose colormap was last downloaded 
in the hardware colormap would look correct. 

Accessing HP Color Recovery Technology via Xlib 

Color Recovery is a technique to generate a better picture by attempting to 
eliminate the graininess caused by dithering. Access to the Color Recovery 
capability is transparent when using a 3D graphics API such as Starbase, HP- 
PHIGS or PEX. If you are producing graphics using Xlib calls, your application 
must perform some of the necessary processing. At server startup (if Color 
Recovery is not disabled in the X*screens hie), the following properties are 
dehned and placed on the root window: 

■ _HP_RGB_SMOOTH_TRUE_MAP 

■ _HP_RGB_SMOOTH_PSEUDO_MAP 

■ _HP_RGB_SMOOTH_MAP_LIST 

These properties are of type RGB_C0L0R_MAP and carry pointers to struc¬ 
tures of type XStandardColormap. They may be interrogated with calls to 
XGetRGBColormaps. The colormaps in the _HP_RGB_SMOOTH_TRUE_MAP and 
_HP_RGB_SMOOTH_PSEUDO_MAP structures identify colormaps which are created 
at server startup and are for use with the TrueColor and PseudoColor visuals, 
respectively. They are both initialized to contain the 3:3:2 ramp of 8-bit True- 
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Color. Neither of these colormaps can be modihed as they are read-only. The 
property _HP_RGB_SMOOTH_MAP_LIST is a list of colormaps that are associated 
with all of the root window’s visual IDs that support Color Recovery. When the 
XGetRGBColormaps routine searches this list for a colormap with a visual ID that 
matches the visual ID that your window is using and it hnds one, your application 
knows that your visual supports Color Recovery, and uses that colormap for any 
Color Recovery window in your window’s visual. 

Note that the algorithm used for the Color Graphics device is slightly different 
from that used for the HCRX family of devices. If you do not wish for your 
application to have to do device-specihc checks, HP recommends that you use 
the HCRX encoding algorithm for Color Recovery regardless of the device on 
which your application is executing. The results on the Color Graphics device 
will not be optimal, but will generally still be much better than a standard 
dither. If you are willing to do device-specihc checks, the existence of either 
the _HP_RGB_SMOOTH_TRUE_MAP or _HP_RGB_SMOOTH_PSEUDO_MAP property will 
indicate the device is Color Graphics. 

Color Recovery uses all 256 entries of one of the available colormaps. The color 
visual used by Color Recovery emulates the 24-bit TrueColor visual; thus, the 
colors red, green, and blue are typically declared as integers in the range from 
0 to 255. Note that each window that uses Color Recovery will have the same 
colormap contents. 

For Color Recovery to produce the best results, the emulated 24-bit TrueColor 
data is dithered as explained below. 

A pixel to be dithered is sent to the routine provided in this example. Note that 
the values of the variables RedValue, Green Value, and BlueValue are generated 
by an application. In this example, the color values are assumed to be in the 
range 0..255. 

The given routine receives the color values and the X and Y window address (Xp 
and Yp) of the pixel. The X and Y address is used to access the dither tables. 
The values from the dither tables are added to the color values. After the dither 
addition, the resultant color values are quantized to three bits of red and green 
and two bits of blue. The quantized results are packed into an 8-bit unsigned 
char and then stored in the frame buffer. In the process of sending the contents 
of the frame buffer to the CRT, a special section in the hardware then converts 
the frame buffer’s 8-bit data into 24-bit TrueColor data for display. 
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Here is a routine that can be used to dither the 24-bit TrueColor data. 


unsigned char dither_pixel_for_CR(RedValue,GreenValue,BlueValue,Xp,Yp) 
int RedValue, GreenValue, BlueValue, Xp, Yp; 

{ 

static short dither_red[2][16] = { 


{-16, 4, -1, 

11, 

-14, 6, -3, 9,-15, 

5, -2, 

10, 

-13, 

7, 

-4, 

8}, 

{ 15, -5, 0, 

static short 

-12, 

13, -7, 2,-10, 14, 

dither_green[2][16] 

-6, 1, 

= { 

-11, 

12, 

-8, 

3, 

-9}}; 

{ 11,-15, 7, 

-3, 

8,-14, 4, -2, 10, 

-16, 6, 

-4, 

9, 

-13, 

5, 

-1}, 

{-12, 14, -8, 
static short 

2, 

-9, 13, -5, 1,-11, 

dither.blue[2][16] 

15, -7, 
= { 

3, 

-10, 

, 12, 

-6, 

0}}; 

{ -3, 9,-13, 

7, 

-1, 11,-15, 5, -4, 

1 

CO 

6, 

-2, 

10, 

-16, 

4}, 

{ 2,-10, 12, 
int 

int 

unsigned char 

-8, 

0,-12, 14, -6, 3, -9, 13, -7, 

red, green, blue; 
x_dither_table, y_dither_table; 
pixel; 

1, 

-11, 

15, 

-5} } 


/* Determine the dither table entries to use based on the pixel address */ 
4 x_dither_table = Xp */, 16; /+ X Pixel Address MOD 16 +/ 

y_dither_table = Yp */, 2; /* Y Pixel Address MOD 2 */ 

/* Start with the initial values as supplied by the calling routine */ 
red = RedValue; 
green = GreenValue; 
blue = BlueValue; 

/* Generate the red dither value */ 

red += dither_red[y_dither_table][x_dither_table]; 

/* Check for overflow or underflow on red value */ 
if (red > Oxff) red = Oxff; 
if (red < 0x00) red = 0x00; 

/* Generate the green dither value */ 

green += dither_green[y_dither_table][x_dither_table]; 

/* Check for overflow or underflow on green value */ 
if (green > Oxff) green = Oxff; 
if (green < 0x00) green = 0x00; 

/* Generate the blue dither value */ 

blue += (dither_blue[y_dither.table][x_dither_table]<<1); 

/* Check for overflow or underflow on blue value */ 
if (blue > Oxff) blue = Oxff; 
if (blue < 0x00) blue = 0x00; 

/* Generate the pixel value by "or"ing the values together */ 

pixel = ((red & OxEO) | ((green & OxEO) >> 3) | ((blue & OxCO) >> 6)); 

return(pixel); 
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Internal Color Graphics, Internal Grayscale Graphics, 
CRX, GRX, and Dual-CRX Device-Dependent Information 


Supported Visuals 

Only one visual is supported. 

For color displays: 

■ Class PseudoColor Depth 8 - 

supports DBF and MBX hardware double-buffering (CRX, Dual CRX) 
supports DBF and MBX software double-buffering (Internal Color Graphics) 

For grayscale displays: 

■ Class Grayscale Depth 8 - 

supports DBF and MBX hardware double-buffering (GRX) 
supports DBF and MBX software double-buffering (Internal GrayScale Graph¬ 
ics) 

The “layer” and “transparent” default visual options are not supported. 

Supported Screen Options 

The following Screen Options are supported: 

■ SwapBuffersOnVBlank 

■ BBitCenterColor (Internal Color Graphics only) 

■ EnableincludeinferiorsFix 
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CRX-24[Z] Device-Dependent Information 


Supported Visuals 

The following visuals are supported: 

■ Class PseudoColor Depth 8 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay - 
supports DBE and MBX software double-buffering 

■ Class DirectColor Depth 12 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class TrueColor Depth 12 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image - 
doesn’t support DBE and MBX double-buffering 

■ Class TrueColor Depth 24 Layer Image - 
doesn’t support DBE and MBX double-buffering 

Supported Screen Options 

The following Screen Options are supported: 

■ CountTransparentInOverlayVisual 

■ SwapBuffersOnVBlank 

■ ImageTextViaBitMap 

■ CRX24_FULL_DEFAULT_VISUAL 

■ EnableincludeinferiorsFix 
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CRX-24[Z] Transparent Overlay Visuals 

The default number of colormap entries in the overlay visual for the CRX-24[Z] 
is 255. Entry 255 is excluded because its value is hard-coded to transparent (that 
is, show the image planes). 

This may have the following two consequences for Xll applications running in 
the overlay planes (the default visual): 

■ Clients attempting to allocate 256 entries do not have their request granted. 

■ Clients requesting (via XAllocNamedColor) the rgb.txt value of “Transpar¬ 
ent” are not returned entry 255. 

This default behavior can be changed by setting the CountTransparentlnOver- 
layVisual screen option. 

When this option is enabled, the X server does the following: 

■ Specihes that the overlay visual has 256 entries. 

■ Creates the default colormap with entry 255 pre-allocated to Transparent. A 
client calling XAllocNamedColor for entry Transparent in the default colormap 
will be returned entry 255. 

■ For all other colormaps, returns all 256 entries as allocable, but issues a warning 
message: 

Warning: XCreateColormap is creating 256 entry cmaps in overlay visual. 

Though allocable, entry 255 is hard-coded to transparency. 

This warning is issued once per server execution. 
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CRX-48Z Device-Dependent Information 


Supported Visuals 

The following visuals are supported: 

■ Class PseudoColor Depth 8 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay - 
supports DBE and MBX software double-buffering 

■ Class DirectColor Depth 24 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class TrueColor Depth 24 Layer Image - 
supports DBE and MBX hardware double-buffering 

Supported Screen Options 

The following Screen Options are supported: 

■ CountTransparentInOverlayVisual 

■ SwapBuffersOnVBlank 

■ ImageTextViaBitMap 

■ EnableincludeinferiorsFix 

CRX-48Z Transparent Overlay Visuals 

The default number of colormap entries in the overlay visual for the CRX-48Z is 
255. Entry 255 is excluded because its value is hard-coded to transparent (that 
is, show the image planes). 

This may have the following two consequences for Xll applications running in 
the overlay planes (the default visual): 

■ Clients attempting to allocate 256 entries do not have their request granted. 

■ Clients requesting (via XAllocNamedColor) the rgb.txt value of Transparent 
are not returned entry 255. 

This default behavior can be changed by setting the CountTransparentlnOver- 
layVisual screen option. 
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When this option is enabled, the X server does the following: 

■ Specihes that the overlay visual has 256 entries. 

■ Creates the default colormap with entry 255 pre-allocated to Transparent. A 
client calling XAllocNamedColor for entry Transparent in the default colormap 
will be returned entry 255. 

■ For all other colormaps, returns all 256 entries as allocable, but issues a warning 
message: 

Warning: XCreateColormap is creating 256 entry cmaps in overlay visual. 

Though allocable, entry 255 is hard-coded to transparency. 

This warning is issued once per server execution. 


4 
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HCRX and HP Visualize Device-Dependent Information 

This section includes information on the HCRX-8[Z], HCRX-24[Z], HP VISUAL- 
ize-EG, HP Visualize-8, HP Visualize- 24, and HP Visualize- 48[XP] graph¬ 
ics devices. 

The HCRX-8[Z] is a one-board device (two, with the optional accelerator) that 
has eight overlay planes, two banks of 8 image planes, and 4 hardware colormaps. 
This device provides a superset of functionality in the CRX. 

The HCRX-24[Z] is a one board device (two, with the optional accelerator) that 
has eight overlay planes, two banks of 12 image planes, and 4 hardware colormaps. 
This device provides a superset of functionality in the CRX-24[Z]. 

The HP Visualize-EG is either an unaccelerated built-in graphics device or a 
single board unaccelerated graphics device (not counting the optional memory 
daughter card in either case). This device provides compatible functionality with 
the Integrated Color Graphics device when in 8 plane mode and has functionality 
compatible with the HCRX-8 device when in double-buffer mode. See below 
for a description of these modes. For shorthand notation, from this point on 
in the document, HP VisUALiZE-EG will refer to either mode, HP VISUALIZE- 
EG(8) will refer to 8 plane mode only and HP [Dual] Visualize-EG will refer to 
double-buffer mode only. 

The HP Visualize-8 is a two board accelerated device that has eight overlay 
planes, two banks of 8 image planes, and 4 hardware colormaps. This device 
provides a superset of functionality in the CRX. 

The HP Visualize-24 is a two board accelerated device that has eight overlay 
planes, two banks of 12 image planes, and 4 hardware colormaps. This device 
provides a superset of functionality in the CRX-24[Z]. 

The HP Visualize-48[XP] is a two-board accelerated device that hlls two slots. If 
you add either the optional texture-mapping memory card or the optional video- 
out card, it becomes a three-board set that hlls three slots. Add both optional 
cards, and it becomes a four-board set, but it still hlls only three slots. In any 
case, it has eight overlay planes, two banks of 24 image planes, and six hardware 
colormaps. This device provides a superset of functionality in the CRX-48Z. The 
hardware support for accelerating 2D Xlib primitives is similar to that in the 
other HCRX devices. The hardware for accelerating 3D geometry, lighting, and 
shading, is new. 
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Supported Visuals 

The following visuals are supported on the HP VISUALIZE-EG(8): 

■ Class PseudoColor Depth 8 Layer Image - 
supports DBE and MBX software double-buffering 

■ Class TrueColor Depth 8 Layer Image - 
supports DBE and MBX software double-buffering 

The following visuals are supported on the HCRX-8[Z], HP [Dual] VISUALIZE-EG 

and HP VisuALiZE-8: 

■ Class PseudoColor Depth 8 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay - (see Note) 
supports DBE and MBX software double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay Transparent - (see Note) 4 

supports DBE and MBX software double-buffering 

■ Class TrueColor Depth 8 Layer Image - 
supports DBE and MBX hardware double-buffering 


Note 



The two overlay visuals are mutually exclusive, based on the 
presence of the EnableOverlayTransparency screen option (i.e., 
if the EnableOverlayTransparency screen option is set, then 
the visual that supports transparency is available, otherwise the 
visual which does not support transparency is available). 
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The following visuals are supported on the HCRX-24[Z] and HP VlsUALlZE-24 

■ Class PseudoColor Depth 8 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay - 
supports DBE and MBX software double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay Transparent - 
supports DBE and MBX software double-buffering 

■ Class TrueColor Depth 8 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class DirectColor Depth 12 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class TrueColor Depth 12 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image - 
doesn’t support DBE and MBX double-buffering 

■ Class TrueColor Depth 24 Layer Image - 
doesn’t support DBE and MBX double-buffering 

The following visuals are supported on the HP VISUALIZE-48[XP]: 

■ Class PseudoColor Depth 8 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay - 
supports DBE and MBX software double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay Transparent - 
supports DBE and MBX software double-buffering 

■ Class TrueColor Depth 8 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image - 
supports DBE and MBX hardware double-buffering 

■ Class TrueColor Depth 24 Layer Image - 
supports DBE and MBX hardware double-buffering 
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Supported Screen Options 

The following Screen Options are supported: 

■ CountTransparentInOverlayVisual 

■ DisableColorRecovery 

■ EnableOverlayTransparency (HCRX-8[Z], HP [Dual] VISUALIZE-EG and 
HP Visualize-8 only) 

■ SwapBuffersOnVBlank 

■ ImageTextViaBitMap 

■ CRX24_FULL_DEFAULT_VISUAL (HCRX-24[Z] only) 

■ EnableincludeinferiorsFix 

HP Visualize-EG Modes 

The following modes are supported: 

■ 8 Plane mode 

■ Double-Buffer mode 

The modes are set from the Boot-Admin at bootup time by selecting from the 
menu of options a conhguration that supports double-buffer or not. From that 
point on (without rebooting) the server will use the selected mode. 

Eight-plane mode is compatible with the Integrated Color Graphics device. It 
has eight image planes and uses only software double-buffering. 

Double-Buffer mode is compatible with the HCRX-8 device. This mode requires 
an optional memory daughter card. If the daughter card is installed, selecting 
this mode will result in eight overlay planes and 16 image planes (the same as 
HCRX-8 and HP Visualize-8 devices). Double-Buffer mode allows the use of 
hardware double-buffering. 


X Windows: HP-UX 10.r 4-51 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


HCRX Configuration Hints 


HCRX-8[Z], HP [Dual] Visualize-EG and HP Visualize-8 Visuals and 
Double-Buffer Support 

The eight-plane HCRX-8[Z], HP [Dual] VisuALiZE-EG and HP Visualize-8 are 
the hrst members of the Series 700 graphics family whose overlay planes and 
image planes are both depth 8. 

■ There are two depth-8 PseudoColor visuals (one in the overlay planes, the other 
in the image planes). There is also a depth-8 TrueColor visual in the image 
planes. 

■ The default visual (where the root window and default colormap reside) is in 
the overlay planes. A Def aultVisual specihcation in a Screen Entry in the 
X*screens hie may instead locate the default visual in the Image Planes (see 
the X*screens Pile section, above). 

■ East 8/8 double-buffering (two hardware buffers) is supported in the depth-8 
image planes, but not in the overlays. The overlay planes support the slower 
virtual-memory-based double-buffering. 

Implications and Suggestions for HCRX-8[Z], HP [Dual] Visualize-EG and 

HP Visualize-8 

The default colormap cannot be used with a window in a non-default visual, even 
one of the same depth as the default visual. 

Before trying to use the default colormap in a depth-8 window, verify that the 
window is in the default visual. If the window is not in the default visual, create 
a colormap in that visual. This process of creating a non-default colormap is the 
same as the one used to create windows in depth-12 or depth-24 visuals. 

If you have an application that assumes that the default colormap can be used 
with any depth-8 window (even one in an image-plane visual) specify an image- 
plane visual as the default. 

Unlike the CRX, the HCRX-8[Z]’s default visual the HP [Dual] VisUALiZE-EG’s 
default visual and the HP VlsUALlZE-8’s default visual do not have fast hardware 
double-buffering (but the image planes do). 

To obtain hardware double-buffering, hud a visual in the image planes. The 
best method is to hud all the depth-8 PseudoColor visuals returned by 
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XGetVisualInfo and then eliminate the visuals that are reported in the 
SERVER_OVERLAY_VISUALS property (discussed below). 

If you have an application that assumes the default visual has fast double¬ 
buffering, specify an image plane visual as the default. 

HCRX Overlay Visuals and Overlay Transparency 

As on the CRX-24[Z] and CRX-48Z, a property on the root window, 

SERVER.OVERLAY.VISUALS, is used to describe the visuals that are in the overlay 
planes. 

Overlay Transparency on the HCRX-8[Z], HP [Dual] Visualize-EG and 

HP Visualize-8 

The HCRX-8[Z], HP [Dual] Visualize-EG and HP Visualize-8 each have one 
visual in the overlay planes (depth-8 PseudoColor). By default, this overlay visual 
has no transparent index available to applications for rendering transparency. 
This means the overlay windows with “floating text” are not supported in the 
typical X server operation on the HCRX-8[Z], HP [Dual] Visualize-EG or HP 
Visualize-8. 

Eor applications that require transparent overlay windows on the HCRX-8[Z], HP 
Visualize-EG(D) or HP Visualize-8, an optional X server mode is available to 
allow for overlay transparency, but it is restrictive. In this optional mode, overlay 
colormaps provide a single entry that can be used to render transparency. Only 
one hardware colormap is available in the overlays (instead of two) and only one 
hardware colormap is available in the image planes (instead of two). 

To activate this optional X server mode to enable transparency, set the 
EnableOverlayTransparency screen option. You will need to restart the X server 
for the option to take effect. 
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With this mode enabled, colormaps created in the default visual have 255 entries; 
entry 256 is reserved for transparency. As on the CRX-24[Z] and CRX-48Z, the 
screen option CountTransparentInOverlayVisual can be used to include the 
transparent index in the colormap size (256 entries instead of 255). 

Programmers’ Note If transparency is not enabled, there are only 252 colors 

available. Entries 252-255 are not writable, and should 
not be used; there are only 252 colormap entries available, 
even though the server states that there are 256. 

Overlay Transparency on the HCRX-24[Z], HP Visualize-24, and 
HP Visualize-48[XP] 

The HCRX-24[Z], HP Visualize-24, and HP Visualize-48[XP] have two visuals 
in the overlay planes, both depth-8 PseudoColor. 

The default overlay visual has 256 entries per colormap and no transparency. 

The second overlay visual has 255 entries per colormap and supports transparency 
in the same way as the CRX-24[Z]. As on the CRX-24[Z] and CRX-48Z, the screen 
option EnableOverlayTransparency can be used to include the transparent 
index in the colormap size (256 entries instead of 255). 

To allow applications to determine which visuals are in the overlay planes, both 
overlay visuals are listed in the SERVER_OVERLAY_VISUALS property attached 
to the root window. The default overlay visual has a transparent type of 
0 (None) while the transparent overlay visual has a transparent type of 1 

(TransparentPixel). 
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If you need an overlay colormap that supports transparency, create the colormap 
using the visual that has transparency in its SERVER_OVERLAY_VISUALS property. 
To look at the contents of this property, you would use code similar to the 
following: 

{ 

typedef struct { 

VisuallD overlayVisuallD; 

Card32 transparentType;/* None, TransparentPixel, TransparentMask */ 

Card32 value; /* Either pixel value or pixel mask */ 

Card32 layer; 

} OverlayVisualPropertyRec; 

OverlayVisualPropertyRec *pOverlayVisuals, *pOVis; 

XVisualInfo getVis; 

XVisualInfo *pVisuals; 

Atom overlayVisualsAtom, actualType; 

/* Get the visuals for this screen and allocate. */ 
getVis.screen = screen; 

pVisuals = XGetVisualInfoCdisplay, VisualScreehWask, ftgetVis, ftnVisuals); 
pOverlayVisuals = (OverlayVisualPropertyRec *) 

malloc ( (size_t)nVisuals * sizeof(OverlayVisualPropertyRec) ); 

/* Get the overlay visual information for this screen. Obtain 
+ this information from the SERVER_OVERLAY_VISUALS property. +/ 
overlayVisualsAtom = XInternAtom(display, "SERVER_OVERLAY_VISUALS", True); 
if (overlayVisualsAtom != None) 

{ 

/* Since the Atom exists, request the property's contents. */ 
bytesAfter = 0; 

numLongs = ( nVisuals * sizeof(OverlayVisualPropertyRec) + 3 ) / 4; 
XGet¥indowProperty(display, Root¥indow(display, screen), 

overlayVisualsAtom, 0, numLongs, False, 

AnyPropertyType, ftactualType, ftactualFormat, 
ftnumLongs, ftbytesAfter, ftpOverlayVisuals); 
if ( bytesAfter != 0 ) {/* Serious Failure Here */} ; 

/* Loop through the pOverlayVisuals array. */ 

nOVisuals = numLongs/sizeof(OverlayVisualPropertyRec); 
pOVis = pOverlayVisuals; 

while (--nOVisuals >= 0) 

{ 

if ( pOVis->transparentType == TransparentPixel ) 

{/* Found a transparent overlay visual, set ident. aside. */}; 
pOVis++; 

} 
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XFree(pOverlayVisuals); 

/* There might be some additional checking of the found 
transparent overlay visuals wanted; e.g., for depth. */ 

} 

XFree(pVisuals); 

} 

This program fragment is not complete; its main purpose is to give the idea of 
how to hnd an overlay visual having transparency. 

HCRX Colormaps 

The following information discusses the number of supported colormaps for the 
HCRX conhgurations. 

HP Visualize-EG(8): 8 Image planes 

The image planes contain the default colormap permanently installed in the 
hardware plus one other hardware colormap available to applications. No issues 
involving transparency exist because of the lack of Overlay planes. 

HCRX-8[Z], HP [Dual] Visualize-EG and HP Visualize-8: Eight Overlay 
Planes and Two Depth-8 Banks of Image Planes 

When the default visual is in the overlay planes (default location) and the screen 
option EnableOverlayTransparency is not set, the overlay planes contain the 
default colormap permanently installed in the hardware, plus one other hardware 
colormap available to applications. The image planes contain two hardware 
colormaps each usable by applications. 

When the default visual is in the image planes and the screen option EnableOver¬ 
layTransparency is not set, the overlay planes contain a single hardware col¬ 
ormap available to applications, plus a colormap reserved by the server (i.e., 
unavailable to applications) to guarantee the existence of transparency, and the 
image planes contain the default colormap permanently installed into the hard¬ 
ware, plus one other hardware colormap available to applications. 

When the screen option EnableOverlayTransparency is set, both the overlay 
planes and the image planes have access to one hardware colormap. The default 
colormap is not permanently installed in the hardware and is in the overlay planes 
by default, but the Default Visual can be located in the image planes as described 
in a previous section. 
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HCRX-24[Z] and HP Visualize-24: Eight Overlay Planes and 24 Image Planes 

The overlay planes contain the default colormap permanently installed in the 
hardware, plus one other hardware colormap available to applications. The image 
planes contain two hardware colormaps, each usable by applications. 

Although two hardware colormaps are available to applications in the image 
planes, a hardware restriction allows only one depth-12 or depth-24 colormap 
to be installed at any given time. Therefore, if two applications are run 
simultaneously and use different depth-12 or depth-24 colormaps, the application 
that has the colormap focus looks correct and the other is technicolored. 

HP Visualize-48[XP]: Eight Overlay Planes and 48 Image Planes 

The overlay planes contain the default colormap permanently installed in the 
hardware, plus one other hardware colormap available to applications. The image 
planes contain four hardware colormaps, each usable by applications. 

The four hardware colormaps in the image planes can be treated as depth-8 or 
depth-24 colormaps. There are no restrictions on the types of colormaps that can 
be installed in the hardware at any given time. All four colormaps can be used 
with any visual class. 

Accessing HP Color Recovery Technology via Xlib 

Color Recovery is a technique to generate a better picture by attempting to 
eliminate the graininess caused by dithering. Access to the Color Recovery 
capability is transparent when using a 3D graphics API such as Starbase, HP- 
PHIGS or PEX. If you are producing graphics using Xlib calls, your application 
must perform some of the necessary processing. At server startup (if Color 
Recovery is not disabled in the X*screens hie), the _HP_RGB_SMOOTH_MAP_LIST 
property is dehned and placed on the root window. 

The above property is of type RGB_C0L0R_MAP and carries pointers to structures 
of type XStandardColormap. It may be interrogated with calls to XGetRGBCol- 
ormaps. The property _HP_RGB_SMOOTH_MAP_LIST is a list of colormaps that 
are associated with window visual IDs that support Color Recovery. When the 
XGetRGBColormaps routine searches this list for a colormap with a visual ID 
that matches your window’s visual ID and it hnds one, your application knows 
that your visual supports Color Recovery, and uses that colormap for any Color 
Recovery window in your window’s visual. 
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Color Recovery uses all 256 entries of one of the available colormaps. The color 
visual used by Color Recovery emulates the 24-bit TrueColor visual, thus, the 
colors red, green, and blue are typically declared as integers in the range from 
0 to 255. Note that each window that uses Color Recovery will have the same 
colormap contents. 

For Color Recovery to produce the best results, the emulated 24-bit TrueColor 
data is dithered as explained below. 

A pixel to be dithered is sent to the routine provided in this example. Note that 
the values of the variables RedValue, Green Value, and BlueValue are generated 
by an application. In this example, the color values are assumed to be in the 
range 0..255. 

The given routine receives the color values and the X and Y window address (Xp 
and Yp) of the pixel. The X and Y address is used to access the dither tables. 
The values from the dither tables are added to the color values. After the dither 
addition, the resultant color values are quantized to three bits of red and green 
and two bits of blue. The quantized results are packed into an 8-bit unsigned 
char and then stored in the frame buffer. In the process of sending the contents 
of the frame buffer to the CRT, a special section in the hardware then converts 
the frame buffer’s 8-bit data into a 24-bit TrueColor data for display. 
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Here is a routine that can be used to dither the 24-bit TrueColor data. 

unsigned char dither_pixel_for_CR(RedValue,GreenValue,BlueValue,Xp,Yp) 
int RedValue,GreenValueBlueValue,Xp,Yp; 

{ 

static short dither_red[2][16] = { 


{-16, 4, -1, 

11, 

-14, 6, -3, 9,-15, 5, 

-2, 

10, 

-13, 

7, 

-4, 

8}, 

{ 15, -5, 0, 

-12, 

13, -7, 2,-10, 14, -6, 

1, 

-11, 

, 12, 

-8, 

3, 

-9}}; 

static short 
{ 11,-15, 7, 

-3, 

dither_green[2][16] = { 
8,-14, 4, -2, 10,-16, 

6, 

-4, 

9, 

-13, 

5, 

-1}, 

{-12, 14, -8, 

2, 

-9, 13, -5, 1,-11, 15, 

-7, 

3, 

-10, 

12, 

-6, 

0}}; 

static short 
{ -3, 9,-13, 

7, 

dither_blue[2][16] = { 
-1, 11,-15, 5, -4, 8,- 

-14, 

6, 

-2, 

10, 

-16, 

4}, 

{ 2,-10, 12, 

-8, 

0,-12, 14, -6, 3, -9, 

13, 

-7, 

1, 

-11, 

15, 

-5}}; 


int red, green, blue; 

int x_dither_table, y_dither_table; 

unsigned char pixel; 


/* Determine the dither table entries to use based on the pixel address */ 
x_dither_table = Xp */, 16; /+ X Pixel Address MOD 16 +/ 

y_dither_table = Yp */, 2; /+ Y Pixel Address MOD 2 +/ 

/* Start with the initial values as supplied by the calling routine */ 
red = RedValue; 
green = GreenValue; 
blue = BlueValue; 

/* Generate the red dither value */ 

if (red >= 48) /* 48 is a constant required by this routine */ 
red=red-16; 
else 

red=red/2+8; 

red += dither_red[y_dither_table] [x_dither_table] ; 

/* Check for overflow or underflow on red value */ 
if (red > Oxff) red = Oxff; 
if (red < 0x00) red = 0x00; 

/* Generate the green dither value */ 

if (green >= 48) /* 48 is a constant required by this routine */ 
green=green-16; 
else 

green=green/2+8; 

green += dither_green[y_dither_table][x_dither_table]; 

/* Check for overflow or underflow on green value */ 
if (green > Oxff) green = Oxff; 
if (green < 0x00) green = 0x00; 
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/* Generate the blue dither value */ 

if (blue >= 112) /* 112 is a constant required by this routine */ 
blue=blue-32; 
else 

blue=blue/2+24; 

blue += (dither_blue[y_dither.table][x_dither_table]<<1); 

/* Check for overflow or underflow on blue value */ 
if (blue > Oxff) blue = Oxff; 
if (blue < 0x00) blue = 0x00; 

pixel = ((red & OxEO) | ((green & OxEO) >> 3) | ((blue & OxCO) >> 6)); 
return(pixel); 


4 
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HP Visualize-FX Device-Dependent Information 

This section includes information on the HP VlsUALlZE-FX^, HP VISUALIZE-PX'^ 
and HP VISUALIZE-PX® graphics devices: 

■ The HP Visualize-FX^ has 8 overlay planes, 24 image planes, a 24-bit Z buffer 
and 8 hardware colormaps. 

■ The HP Visualize-FX'^ has 8 overlay planes, 48 image planes, a 24-bit Z buffer 
and 8 hardware colormaps. 

■ The HP Visualize-FX® has 8 overlay planes, 48 image planes, 16 alpha planes, 
a 24-bit Z buffer and 8 hardware colormaps. 

HP Visualize-FX graphics devices contain 2D hardware acceleration similar to 
that in other HP Visualize devices as well as 3D acceleration for geometry, 
lighting, and shading. Optional texture mapping acceleration is also available. 

4 

Supported Visuals 

HP Visualize-FX graphics devices support all of the following visuals: 

■ Class PseudoColor Depth 8 Layer Image 

■ Class PseudoColor Depth 8 Layer Overlay 

■ Class PseudoColor Depth 8 Layer Overlay Transparent 

■ Class TrueColor Depth 8 Layer Image 

■ Class PseudoColor Depth 12 Layer Image 

■ Class DirectColor Depth 12 Layer Image 

■ Class TrueColor Depth 12 Layer Image 

■ Class DirectColor Depth 24 Layer Image 

■ Class TrueColor Depth 24 Layer Image 
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The following visuals are enabled by default on the HP VISUALIZE-FX^: 

■ Class PseudoColor Depth 8 Layer Image- 
supports DBE hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay- 
supports DBE software double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay Transparent- 
supports DBE software double-buffering 

■ Class TrueColor Depth 8 Layer Image- 
supports DBE hardware double-buffering 

■ Class DirectColor Depth 12 Layer Image- 
supports DBE hardware double-buffering 

■ Class TrueColor Depth 12 Layer Image- 
supports DBE hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image- 

does not support DBE hardware or software double-buffering 

■ Class TrueColor Depth 24 Layer Image- 

does not support DBE hardware or software double-buffering 

The default set of visuals on the HP VISUALIZE-FX'^ and HP VISUALIZE-FX® 

depend on the stereo mode setting. 

In non-stereo mode, the following visuals are enabled by default on the 

HP Visualize-FX'^ and HP Visualize-FX®: 

■ Class PseudoColor Depth 8 Layer Image- 
supports DBE hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay- 
supports DBE software double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay Transparent- 
supports DBE software double-buffering 

■ Class TrueColor Depth 8 Layer Image- 
supports DBE hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image- 
supports DBE hardware double-buffering 

■ Class TrueColor Depth 24 Layer Image- 
supports DBE hardware double-buffering 
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In stereo mode, the following visuals are enabled by default on the 

HP Visualize-FX'^ and HP Visualize-FX®: 

■ Class PseudoColor Depth 8 Layer Image - 
supports DBF hardware double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay - 
supports DBF software double-buffering 

■ Class PseudoColor Depth 8 Layer Overlay Transparent - 
supports DBF software double-buffering 

■ Class TrueColor Depth 8 Layer Image - 
supports DBF hardware double-buffering 

■ Class DirectColor Depth 12 Layer Image - 
supports DBF hardware double-buffering 

■ Class TrueColor Depth 12 Layer Image - 
supports DBF hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image - 4 

supports DBF hardware double-buffering 

■ Class TrueColor Depth 24 Layer Image - 
supports DBF hardware double-buffering 


Note 



Note: When running xdpyinfo or calling the XGetVisualInfoO 
Xlib function, some extra duplicate visuals may appear in the 
visual list. These extra visuals are created on behalf of the 
OpenGL extension to X (GLX). If necessary, the extra visuals 
can be disabled using the DisableGlxVisuals screen option. See 
“Disabling the GLX Visuals” below for more information. 


Supported Screen Options 

The following Screen Options are supported: 

■ Count TransparentInOverlay Visual 

■ ImageTextViaBitMap 

■ EnableIncludeInferiorsFix 

■ Enablel2BitPseudoColorVisual 

■ DisableGlxVisuals 
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The following additional screen options are supported on the HP VISUALIZE-FX^, 
HP Visualize-FX'^ (stereo mode) and HP Visualize-FX® (stereo mode): 

■ Disablel2BitDirectColorVisual 

■ Disablel2BitTrueColorVisual 

The following additional screen options are supported on the HP VISUALIZE-40FX 
(non-stereo mode) and HP V 1 SUALIZE- 8 OFX (non-stereo mode): 

■ Enablel2BitDirectColorVisual 

■ Enablel2BitTrueColorVisual 

HP Visualize-FX Configuration Hints 
Overlay Visuals and Overlay Transparency 

HP Visualize-FX devices have two visuals in the overlay planes, both depth-8 
PseudoColor. The hrst (default) overlay visual has 256 entries per colormap and 
no transparency. The second overlay visual has 255 entries per colormap and 
supports transparency. 

To allow applications to determine which visuals are in the overlay planes, both 
overlay visuals are listed in the “SERVER_OVERLAY_VISUALS” property attached 
to the root window. The default overlay visual has a transparent type of 
“0” (None) while the transparent overlay visual has a transparent type of “1” 

(TransparentPixel). 
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If you need an overlay colormap that supports transparency, create the colormap 
using the visual that has transparency in its SERVER_OVERLAY_VISUALS property. 

To look at the contents of this property, you would use code similar to the 
following: 

{ 

typedef struct { 

VisuallD overlayVisuallD; 

Card32 transparentType;/* None, TransparentPixel, TransparentMask */ 

Card32 value; /* Either pixel value or pixel mask */ 

Card32 layer; 

} OverlayVisualPropertyRec; 

OverlayVisualPropertyRec *pOverlayVisuals, *pOVis; 

XVisualInfo getVis; 

XVisualInfo *pVisuals; 

Atom overlayVisualsAtom, actualType; 

/* Get the visuals for this screen and allocate. */ 4 

getVis.screen = screen; 

pVisuals = XGetVisualInfoCdisplay, VisualScreehWask, ftgetVis, ftnVisuals); 
pOverlayVisuals = (OverlayVisualPropertyRec *) 

malloc ( (size_t)nVisuals * sizeof(OverlayVisualPropertyRec) ); 

/* Get the overlay visual information for this screen. Obtain 
+ this information from the SERVER_OVERLAY_VISUALS property. +/ 
overlayVisualsAtom = XInternAtom(display, "SERVER_OVERLAY_VISUALS", True); 
if (overlayVisualsAtom != None) 

{ 

/* Since the Atom exists, request the property's contents. */ 
bytesAfter = 0; 

numLongs = ( nVisuals * sizeof(OverlayVisualPropertyRec) + 3 ) / 4; 

XGet¥indowProperty(display, Root¥indow(display, screen), 

overlayVisualsAtom, 0, numLongs, False, 

AnyPropertyType, ftactualType, ftactualFormat, 
ftnumLongs, ftbytesAfter, ftpOverlayVisuals); 
if ( bytesAfter != 0 ) {/* Serious Failure Here */} ; 

/* Loop through the pOverlayVisuals array. */ 

nOVisuals = numLongs/sizeof(OverlayVisualPropertyRec); 
pOVis = pOverlayVisuals; 
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while (--nOVisuals >= 0) 

{ 

if ( pOVis->transparentType == TransparentPixel ) 

{/* Found a transparent overlay visual, set ident. aside. */}; 
pOVis++; 

} 

XFree(pOverlayVisuals); 

/* There might be some additional checking of the found 
transparent overlay visuals wanted; e.g., for depth. */ 

} 

XFree(pVisuals); 

} 

This program segment is not complete; however, its main purpose is to give an 
idea of how to hnd an overlay visual having transparency. 

Disabling the GLX Visuals 

The HP Visualize-FX products are the hrst set of HP graphics devices that 
supports the OpenGL extension to X (GLX). If HP OpenGL is installed on an 
HP Visualize-FX system, then the GLX extension offers new entry points for 
obtaining more information about X visuals. As part of offering extended visual 
information, some extra X visuals appear in the X visual list. The extra visuals 
are simply duplicates of visuals that would normally appear in the X visual list. 
In case that the extra visuals cause problems with applications, a screen option 
can be used to disable them. 

To disable the GLX visuals, add the DisableGlxVisuals Screen Option to the 
X*screens hie. For example: 

Screen /dev/crt/ 

SereenOptions 
DisableGlxVisuals 
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HP Visualize-FX Colormaps 

HP Visualize-FX devices have a total of 8 hardware colormaps. Two of the 
colormaps are dedicated to the overlay planes, and the remaining six colormaps 
are dedicated to the image planes. 

Of the 2 overlay colormaps, one is permanently reserved for the default colormap. 
The other overlay colormap is available to applications. 

Of the 6 image colormaps, two are reserved for the 12-bit PseudoColor visual. 
The other 4 image colormaps are available for applications using other image 
plane visuals. 

Changing the Monitor Type 

A conhguration tool is available to change the monitor type on HP VisUALiZE-FX 
devices. Monitor resolution, refresh rate and stereo mode settings may 
be conhgured using the setmon tool. To change the monitor type, the 
setmon command can be executed directly or done through the SAM system 
administration tool. 

The setmon executable is located at /opt/graphics/common/bin/setmon. Un¬ 
der SAM this component is located under the top-level “Display” folder, next to 
the “X Server Conhguration” icon. 


Note 



Changing the monitor type while the X server is running will 
necessitate killing and restarting the X server. 
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Freedom Series Graphics Device-Dependent Information 

This sections describes support for the Freedom Series from Evans & Sutherland 
on Hewlett-Packard workstations. 


Note 



Note that the Freedom Series is no longer supported as of HP- 
UX 10.30; the information below is presented for those who are 
running previous versions of the operating system. 


Supported Visuals 

The following visuals are supported: 

■ Class PseudoColor Depth 8 Layer Overlay - 
Class PseudoColor Depth 8 Layer Image - 
supports DBF and MBX hardware double-buffering 

■ Class DirectColor Depth 24 Layer Image - 
supports DBF and MBX hardware double-buffering 

■ Class TrueColor Depth 24 Layer Image - 
supports DBF and MBX hardware double-buffering 

Supported Screen Options 

The following Screen Options are supported: 

■ FreedomVideoFormat 
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Freedom Video Formats 

Freedom Series graphics devices have the ability to support several different 
video formats. The default format is 1280x1024 @ 75 Hz VESA timing. Other 
supported video formats may be selected by using the FreedomVideoFormat 
screen option in the appropriate X*screens hie. This screen option replaces 
the 9.07 environment variable, ES_VIDE0_F0RMAT. The appropriate video format 
must be selected to support the specihc display device connected to the Freedom 
accelerator. Multisync monitors can support several different video formats. 

Alternative supported formats: 


Table 4-2. Alternative Supported Freedom Video Formats 


Screen Option 

Resointion 

Description 

ntsc_cvo 

640x480 

U.S. composite TV format with CVO* 

pal_cvo 

768x576 

European composite TV format with CVO* 


* “CVO” is the Composite Video Output card, which must be installed in the 
Freedom accelerator for this video format to work. 

While the following formats are provided there is no intent to claim “support” 
for these formats, they are untested and unsupported conhgurations. 
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Alternative unsupported formats: 


Table 4-3. Alternative Unsupported Freedom Video Formats 


Screen Option 

Resointion 

Description 

ntsc 

640x480 

U.S. composite TV format 

pal 

768x576 

European composite TV format 

hdtv 

1920x1024 

60 Hz interlaced 

stereol 

640x512 

60 Hz frame rate per eye 

stereo2 

1280x512 

60 Hz frame rate per eye 

vga 

640x480 

Standard VGA 

video60 

1280x1024 

60 Hz 

video76 

1280x1024 

76 Hz 
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VRX Device-Dependent Information 

This section includes information on the PersonalVRX (PVRX) and TurboVRX 
(TVRX) graphics devices. 


Note 



Note that the PersonalVRX and the TurboVRX are no longer 
supported as of HP-UX 10.30; the information below is presented 
for those who are running previous versions of the operating 
system. 


Supported Visuals 

The following visuals are supported: 

■ Depth 3 (overlay and combined mode) 

■ Depth 4 (overlay and combined mode) 

■ Depth 8 (image and combined mode) 

■ Depth 12 (image and combined mode, TVRX only) 

■ Depth 16 (Creates a double-buffer version of the Depth 8 visual) 

■ Depth 24 (image and combined mode, TVRX only) 

None of these visuals support DBE or MBX double-buffering. 

In image mode the default visual is the Depth 8 PseudoColor visual. In overlay 
mode it is the depth 3 or depth 4 PseudoColor visual as specihed by the device 
hie. In combined mode the hrst device hie specihes the default visual. Examples 
are shown in the section below. 

VRX Device Files 

Different device hies exist for the image planes and overlay planes on VRX devices. 
The X server supports three different modes of operation on VRX devices: image, 
overlay or combined. 

In image mode, the X server runs only in the image planes. This is the default on 
VRX devices. To operate in image mode, the image device hie should be specihed 
as the primary screen device. Eor example: 

/dev/crt # Image mode 
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In overlay mode, the X server runs only in the overlay planes. Since only 3 or 4 
planes are available in the overlay planes on VRX devices, the number of colors 
is very limited. To operate in overlay mode, the overlay device hie should be 
specihed as the primary screen device. For example: 


/dev/ocrt # Overlay mode using 3 overlay planes 

or 

/dev/o4crt # Overlay mode using 4 overlay planes 

In combined mode, the X server runs in both image and overlay planes. To 
conhgure the X server to operate in combined mode, a primary and a secondary 
device must be specihed. The VRXSecondaryDevice is used for this purpose. For 
example: 


/dev/ocrt /dev/crt 

or 

/dev/crt /dev/ocrt 


# default visual lives in overlay planes 

# default visual lives in image planes 
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X Windows Configuration Details 


This chapter discusses several details concerning the conhguration of X hosts, 
colormaps, mouse, and keyboard. 


Making an X*.hosts File 

The /etc/XO .hosts hie is an ASCII text hie containing the hostnames of each 
remote host permitted to access your local server. 

■ If you are running as a stand-alone system, you must have your system’s name 
in this hie. 

■ If you are part of a network, the other system names must be included. 

The syntax is as follows: 

{host) 

{host) 

{host) 

For example, if you are hpaaaaa, and regularly ran clients on hpccccc, and 
hpddddd, you would want the following lines. 

hpaaaaa 

hpccccc 

hpddddd 

Note that aliases work as well as hostnames, provided they are valid, that is, 
commonly known across the network. 


X Windows Configuration Detaiis 5-1 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


xo.hosts and xoscreens Ralation 


The default screen configuration file XOscreens uses the default Xll remote host 
hie XO .hosts. 

Each custom Xoscreens hie is associated with a special X*.hosts hie. The 
number represented by the causes the correct screen and host hies to be used 
together. For example, X3screens takes an X3.hosts hie. Both are referenced 
by the server when it is started with a /usr/bin/Xll/X :3 command. 

If you use a special Xoscreens hie, you need to set your DISPLAY variable 
appropriately. For the previous example, it would be set to hostname:3.0. 


Note 



The number in an Xnscreens hie does not necessarily refer to a 
physical screen number; any meaning implied by the number is for 
the user to dehne. There are no semantics applied to the number 
except that the Xnscreens hies are used when X is started on 
display [name): n .0. For example, an X3screens hie does not 
necessarily imply device hie /dev/crt3; an X3screens hie can 
use whatever device hie the user specihes. The same applies to 
the X*devices, X*.hosts, X* .pointerkeys, etc., hies as well. 


Using an /etc/hosts File 

This hie need not be present if your system is conhgured to query a nameserver. 

The /etc/hosts hie is an ASCII text hie containing a list of all the host names 
and internet addresses known to your system, including your own system. 

If your system is not connected to a network, use the loopback address 
(127.0.0.1) and the hostname unknown: 

127.0.0.1 unknown 

For a local system to access a remote host: 

■ The address and hostname of the remote host must be listed in the local 
system’s /etc/hosts hie. 

■ The user must have a valid login (username and password) and home directory 
on the remote host. 
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Using Special Input Devices 

Input devices are connected to Hewlett-Packard computers through several 
different hardware interfaces. Among the interfaces supported are the Hewlett- 
Packard Human Interface Link (HP-HIL) and the industry standard RS-232C 
(serial) and DIN interfaces. Some Hewlett-Packard computers do not support all 
of these interfaces. 

How the X Server Chooses the Default Keyboard and Pointer 

The X server can access input devices through any of the above interfaces. Devices 
that use the HP-HIL interface and devices that use the DIN interface and are 
compatible with the HP DIN keyboard and mouse can be used by simply plugging 
them into the computer. Devices that use the RS-232C interface require the 
installation of input device driver software before they can be used. 

If no explicit input device conhguration is done, the X server chooses the X 
keyboard device and X pointer device from the input devices that are connected 
to the computer (in most cases, the keyboard and a mouse). On computers that 
support both HP-HIL and DIN interfaces, the DIN input devices are used if both 
types of devices are connected. 

HP-HIL input devices can plug into other HP-HIL devices, with up to seven 
input devices connected together. If there are no DIN input devices connected, 
and there are multile HP-HIL input devices, the following algorithm is used to 
choose an X keyboard and pointer device. 

1. If no explicit specihcation is made through the X*devices hie, the last mouse 
(the one farthest from the computer on the HP-HIL line) is used as the X 
pointer and the last keyboard is used as the X keyboard. 

2. If no mouse is available, the last pointing device (such as a dial box, graphics 
tablet, or trackball) is used as the X pointer. If no keyboard is available, 
the last key device (such as a buttonbox or barcode reader) is used as the X 
keyboard. 

3. If either the pointer or keyboard are unavailable, the X server won’t run unless 
explicitly conhgured to run with no input devices. 
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X*devices File 


The X server reads an input device file, XOdevices in /etc/Xll, to find out what 
input devices it should open and attach to the display. 


Note 



A sample XOdevices file is loaded into /etc/Xll unless one 
already exists. In that case, it is in /usr/newconf ig/etc/Xll. 


The default XOdevices file contains lines of text, but does not specify any input 
configuration. Rather, it assumes the default input configuration of one keyboard 
and one pointer. 

If this is your configuration, you may not want to change the contents of the file 
for these reasons: 

■ Clients can request and receive the services of an input device regardless of 
whether the device is specified in a device configuration file. Thus, you need 
not change the XOdevices file, or create a custom file, even though you have a 
custom input configuration. 

■ Even if you have other screen configurations, you can rely on the default input 
device configuration without having to create an XOdevices file to match every 
X*screens file. For example, if you had a custom X*screens file, you would 
not necessarily need an XOdevices file. 

A custom XOdevices file is required only when you want to tell the X server 
about a custom input device configuration. 

Explicitly Specifying Input Device Use 

The X server can be explicitly configured to use a specific input device as the X 
pointer or X keyboard, or merge the data from an input device with that from 
the X pointer or keyboard. This configuration is done by adding information to 
the XOdevices file. There is one syntax to use for HP-HIL devices, and another 
syntax for devices that require a device driver to be loaded by the X server (such 
as RS-232 devices). 
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HP-HIL devices can be specified in either of two ways: 

■ Device type and position. 

■ Device file name. 


Explicitly Specifying RS-232 Input Device Use 

Some RS-232C input devices can be used with the X server. A device driver 
must exist for the desired serial input device, and it must reside in the 
/usr/lib/Xll/extensions directory. Input device drivers are usually supplied 
by the input device vendor along with the input device. Sample input device 
drivers and documentation describing how to write an input device driver may 
be found in the /usr/contrib/Xlldrivers/input directory. 

To use an RS-232 input device, you must modify the X*devices file to inform 
the X server which input device driver is to be loaded, the serial port to which 
it is connected, and how it is to be used. This is done by adding an entry to the 
X*devices file of the following form: 

Begin_Device_Description 
Name {device_drwer_name) 

Path {device_file_path) 

Use {device_use) 

End_Device_Description 

where: 


{device_driver_name) 


Specifies the name of the input device driver shared 
library. 


{device_file_path) Specifies the name of the device file for the serial port 

being used. 

{device_use) Specifies the desired use of the input device, such as 

“keyboard”, “pointer”, “other”, or “extension”. 
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The following example specifies a Spatial System Spaceball® connected to the 
serial port associated with device hie /dev/ttyOO as the X pointer: 


Begin_Device_Description 
Name spaceball.si 

Path /dev/ttyOO 

Use pointer 

End_Device_Description 


More examples of input device specihcations for RS-232 input devices are in the 

/usr/newconfig/etc/Xll/XOdevices hie. 


Specifying HP-HIL Input Device Use by Device Type and Position 

The device can be specihed using its device type and position by adding an entry 
to the X*devices hie with the following form: 

{relative_position) [device_type) [use) ^[comments) 

where: 


[relative_position) 


[device_type) 


[use) 

^[comments) 


Specihes the position of the device on the HP-HIL 
relative to the other devices on the HP-HIL, for example, 
“first”, “second”, and so on. 

Specihes the type of input device, such as “keyboard”, 
“mouse”, or “tablet”. 

Is “keyboard”, “mouse”, or “other”. 

Describes device. Comments are optional, but if present, 
must start with a “#”. 


Separate the parts of your entry with tabs or spaces. 

The position of an input device on the HP-HIL is relative to other devices of 
the same type. For example if you have two keyboards, a graphics tablet, 
and a mouse connected, they are referred to as “first keyboard”, “second 
keyboard”, “first tablet”, and “first mouse”. 

This syntax is useful for computers on which a single X server is running, and on 
which no other programs directly access input devices. With this syntax, if you 
add a new input device to the HP-HIL, you don’t have to edit the X*devices hie 
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unless the device is of the same type as one already named in the hie and you 
add the device ahead of the existing device. 

This syntax should not be used if more than one X server will be run on the same 
computer, or if non-X programs will be directly accessing input devices. The X 
server interprets “hrst” to mean “hrst accessible”, so you may not always get the 
hrst on the HP-HIL, just the hrst one not already in use. 


5 
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Selecting Values for X*devices Files 

X*devices files use the following special names for positions, devices, and uses: 


Table 5-1. Values for x*devices Files 


Positions 

Device Type (Device Class) 

Uses 

first 

keyboard (keyboard) 

keyboard 

second 

mouse (pointer) 

pointer 

third 

tablet (pointer) 

other 

fourth 

buttonbox (keyboard) 


fifth 

barcode (keyboard)^ 


sixth 

one_knob (pointer) 


seventh 

nine_knob (pointer)^ 



quadrature (pointer) 



touchscreen (pointer) 



trackball (pointer)^ 



null 



1. Note also that the HP barcode reader has two modes: keyboard and ASCII. 
The modes are set via switches on the reader. If you set the barcode reader to 
ASCII transmission mode, it appears to the server as a barcode reader and the 
device name is therefore barcode. However, if you set the barcode reader to 
emulate a keyboard, the barcode reader appears as a keyboard and the device 
name should therefore be keyboard. What distinguishes a barcode reader set 
to keyboard mode from a real keyboard is the relative position or the device 
file name, depending on which syntax you use. 

2. The nine-knob box appears to the X server as three separate input devices. 
Each row of knobs is a separate device, and the first device is the bottom row. 

3. Similar to the barcode reader, the trackball appears to the server, not as a 
trackball, but as a mouse. Therefore, to specify a trackball, use the mouse 
device name. Again, what specifies the trackball instead of the real mouse is 
the relative position or the device filename, depending on which syntax you 
use. 
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Examples 


You can create a system on which the X server runs, but which does not have 
any input devices. In this case, clients could be run from a remote terminal, or 
from a remote host, and their output directed to the X server. To create a system 
with no input, include the following lines in the XOdevices hie: 

first null keyboard 

first null pointer 

If you had a more complicated conhguration, such as two graphics tablets, two 
keyboards, and a barcode reader, your X*devices hie could look like this: 

■ first tablet pointer The pointer 

■ second tablet other Merged with the pointer 

■ first keyboard other Merged with the keyboard 

■ second keyboard keyboard The keyboard 

■ first barcode other Merged with the keyboard 

In this example, the hrst tablet acts as the pointer, the second keyboard acts as 
the keyboard, input from the second tablet is treated as if it came from the X 
pointer, and input from the hrst keyboard and the barcode reader is treated as 
if it came from the X keyboard. 

Note that the barcode reader is in ASCII mode in this example. If the barcode 
reader were in keyboard mode, the last line of the example would read as follows: 

third keyboard other 

More examples can be found in the XOdevices hie in /usr/newconf ig/etc/Xll. 
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Specifying HP-HIL Input Device Use by Device File Name 

The device can be specified using the name of the device to which it is attached. 
This can be done by adding an entry to the X*devices file with the form: 

/{path)/device_file {use) ^{comments) 

where: 

{path)/{device_file) Specifies the name of the device file associated with the 

input device. 

{use) is “keyboard”,“pointer”,or “other”. 

^{comments) Describes the device. Comments are optional, but if 

present, must be preceded by a “#”. 

This syntax should be used if more than one X server will be running on the 
computer, or if non-X programs will be accessing the input devices. It refers to 
a specific position on the HP-HIL. 

Redefining the HP-HIL Search Path 

The X*devices file can be used to redefine the path searched for HP-HIL devices. 
By default, the path searched is /dev/hil. The device files are named by 
appending the numbers “1” through “7” to the path. 

The path is redefined by adding an entry to the X*devices file with the following 
form: 

{path) {hil_path) ^{comment) 
where: 

{path) Specifies the path to be searched for the HP-HIL input 

devices. 

^{comments) Describes the path. Comments are optional, but if 

present, must be preceded by a “#”. 

The X server appends the numbers “1” through “7” to the specified path. For 
example, specifying: 

/tmp/fred hil_path 

results in the device names /tmp/fredl, /tmp/fred2, and so on. 
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stopping the X Window System 

After stopping all application programs, stop the window system by holding down 
the [Ctrl ') and left [ Shift ") keys, and then pressing the [Reset ") key. This stops the 
display server, and with it the window system. (If you have a PC-style keyboard, 
press [ Shift") [Ctrl') [Pause) instead.) 

The sequence of keys that stops the display server can be customized in the 

X*pointerkeys hie. Refer to the XOpointerkeys hie in /etc/Xll. 


5 
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Initializing the Colormap with xinitcolormap 

The xinitcolormap client initializes the X colormap. Specihc X colormap entries 
(pixel values) are made to correspond to specihed colors. An initialized colormap 
is required by applications that assume a predehned colormap (for example, many 
applications that use Starbase graphics). 


xinitcolormap has the following syntax: 
xinitcolormap [{options)] 
where the [options) are: 

-f [colormapfile) Specihes a hie containing a colormap. 

Specihes the server to connect to. 


-display [display) 
-c [count) 

-k or -kill 


Only the hrst count colors from the colormap hie will be 
used if this parameter is specihed. 

Deallocate any colormap entries that were allocated by a 
previous run of xinitcolormap. 


xinitcolormap choses a colormap hie in the order shown below. Once one is 
found, then the other sources aren’t searched. 

1. The command line option [-f [colormapfile)]. 

2. .Colormap default value. 

3. The xcolormap hie in /usr/lib/Xll. 

4. If no colormap hie is found, this default colormap specihcation is assumed— 
black (colormap entry 0), white, red yellow, green, cyan, blue, magenta 
(colormap entry 7). 

xinitcolormap should be the hrst client program run at the start of a session in 
order to assure that colormap entries have the color associations specihed in the 
colormap hie. Sometimes you may encounter this X toolkit warning: 

X Toolkit Warning: cannot allocate colormap entry for 94c4d0 


where “94c4d0” is a color specihed in the application running. If this occurs, 
it means that you have probably reached the limit of colors for your graphics 
card/display combination. Executing xinitcolormap may solve the problem. 

For more information about xinitcolormap, refer to its reference page. 
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Customizing the Mouse and Keyboard 

This section describes the following customizations: 

■ Changing mouse button actions. 

■ The xmodmap client. 

■ Going mouseless. 

■ Customizing keyboard input. 

Related information: 

■ Chapter 7 contains mwm mouse and keyboard bindings. 

Changing Mouse Button Actions 

Normally, the mouse pointer buttons are mapped as follows: 


Table 5-2. Default Mouse Button Mapping 


Button Number 

Button on a 2-button 

mouse 

Button on a 3-button Mouse 

Button 1 

Left button 

Left button 

Button 2 

Both buttons 
simultaneously 

Middle button 

Button 3 

Right button 

Right button 

Button 4 


Left and middle buttons 
simultaneously 

Button 5 


Middle and right buttons 
simultaneously 
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However, you can change these mappings. To generate buttons 4 and 5 on a 
three-button mouse, you must enable button chording as described later in this 
chapter. 


Table 5-3. Alternative Mouse Button Mappings 


To press: 

Left-Handed Mapping 

OSF/Motif Mapping 

2-bntton nionse 

3-button mouse 

2-button mouse 

3-button mouse 

Button 1 

Right button 

Right button 

Left button 

Left button 

Button 2 

Both buttons 
simultaneously 

Middle button 

Right button 

Middle button 

Button 3 

Left button 

Left button 

Both buttons 
simultaneously 

Right button 

Button 4 


Middle and right 
buttons 
simultaneously 


Left and middle 
buttons 
simultaneously 

Button 5 


Middle and left 
buttons 
simultaneously 


Right and middle 
buttons 
simultaneously 


The xmodmap utility can be used to change mouse button mappings. The syntax 
for changing mouse button mappings with xmodmap is: 


xmodmap 

{-e "pointer = 

{default I number Inumber. . .] }" | 

-pp> 


-e 


default 

number 


PP 


Specihes a remapping expression. Valid expressions are 
covered in “Customizing Keyboard Input”. 

Set mouse keys back to default bindings. 

Specihes a list of button numbers to map the mouse keys 
to. The order of the numbers refers to the original button 
mapping. 

Print the current pointer mapping. 
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For example, to reverse the positions of buttons 1 and 3 for left-handed mapping: 


xmodmap -e "pointer = 321" (2-hutton mouse) 

xmodmap -e "pointer = 3 2 1 5 4" (3-button mouse) 

To establish OSF/Motif-standard button mapping: 

xmodmap -e "pointer =132" 2-button mouse 

xmodmap -e "pointer =13245" 3-button mouse 


Going Mouseless with the x*pointerkeys File 

Your work situation may lack sufficient desk space to adequately use a mouse 
pointer. You may, therefore, want to “go mouseless” by naming the keyboard (or 
some other input device) as the pointer. 

To go mouseless, you need to have the proper conhguration specihed in the 
X*devices hie and to have a special conhguration hie named X*pointerkeys. 

The default X*pointerkeys hie is XOpointerkeys in /usr/lib/Xll. 

The X*pointerkeys hie lets you specify: 5 

■ The keys that move the pointer. 

■ The keys that act as pointer buttons. 

■ The increments for movement of the pointer. 

■ The key sequence that resets Xfl. 

■ The pixel threshold that must be exceeded before the server switches screens. 

■ That button chording is enabled or disabled. 

■ That button latching is enabled or disabled. 

■ Tablet subsetting. 

■ Screen switching behavior for multi-screen conhgurations. 

If you modify a X*pointerkeys hie, it does not take effect until you restart the 
X server. 
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Configuring X^devices for Mouseiess Operation 

If you have only one keyboard and no pointer device, and you want the keyboard 
to serve as both keyboard and pointer, you don’t have to change the default 
conhguration of XOdevices. The default input device conhguration automatically 
assigns the pointer to the keyboard if a pointer can’t be opened by the server. 

If you have two or more input devices, you may need to explicitly specify which 
device should be the keyboard and which the pointer. 

The Defauit Vaiues for the X*pointerkeys Fiie 

By default, when you conhgure your keyboard as the pointer, the X server chooses 
certain number pad keys and assigns them mouse operations. Some number pad 
keys are assigned to pointer movement; other number pad keys are assigned to 
button operations. 

If you don’t need to change the pointer keys from their default specihcations, 
you don’t need to do anything else to use your keyboard as both keyboard and 
pointer. However, if you need to change the default pointer keys, you must edit 
the XOpointerkeys hie or create a new X*pointerkeys hie. The X*pointerkeys 
hie is the hie that specihes which keys are used to move the pointer when you 
use the keyboard as the pointer. 

The default key assignments are listed in the tables in the following section on 
customizing the X*pointerkeys hie. 

Creating a Custom X*pointerkeys File 

You need to modify the existing XOpointerkeys hie only if one or more of the 
following statements are true: 

■ You want to use the keyboard for a pointer. 

■ You want to change the pointer keys from their default conhguration. 

■ You use the XOscreens hie to conhgure your display. 

You need to create a custom X*pointerkeys hie only if the following statements 
are true: 

■ You want to use the keyboard for a pointer. 

■ You want to change the pointer keys from their default conhguration. 

■ You use a conhguration hie other than the XOscreens hie to conhgure your 
display. 
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Syntax. You assign a keyboard key to a mouse function (pointer movement or 
button operation) by inserting a line in the X*pointerkeys file. Lines in the 
X*pointerkeys hie have the syntax: 

{function) {keyname) [# {comment)] 

Assigning Mouse Functions to Keyboard Keys. You can assign any mouse 
function, either a pointer movement or a button operation, to any keyboard 
key. However, make sure that the key you are assigning doesn’t already serve a 
vital function. 

You can assign keyboard keys to pointer directions by specifying options in an 
X*pointerkeys hie. The following table lists the pointer movement options, the 
X*pointerkeys functions that control them, and their default values: 


Tabie 5-4. Pointer Movement Functions 


Movement Option 

Function 

Default Key 

Move the pointer to the left. 

pointer_left_key 

keypad_l 

Move the pointer to the right. 

pointer_right_key 

keypad_3 

Move the pointer up. 

pointer_up_key 

keypad_5 

Move the pointer down. 

pointer_down_key 

keypad_2 

Add a modiher key to the pointer 
direction keys. 

pointer_key_modl 

(no default) 

Add a second modiher key to the pointer 
direction keys. 

pointer_key_mod2 

(no default) 

Add a third modiher key to the pointer 
direction keys. 

pointer_key_mod3 

(no default) 


Note that the pointer direction keys are the keypad number keys on the right side 
of the keyboard, not the keyboard number keys above the text character keys. 
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You can assign keyboard keys to pointer distances by specifying options in a 
XOpointerkeys file. The following table lists the options that determine the 
distance of pointer movements, the X*pointerkeys functions that control them, 
and their default value: 


Table 5-5. Pointer Distance Functions 


Movement 

Function 

Default 

Move the pointer a number of pixels 

pointer_move 

10 pixels 

Move the pointer using a modiher key 

pointer_modl_amt 

40 pixels 

Move the pointer using a modiher key 

pointer_mod2_amt 

1 pixel 

Move the pointer using a modiher key 

pointer_mod3_amt 

5 pixels 

Add a modiher to the distance keys 

pointer_amt_modl 

no default 

Add a modiher to the distance keys 

pointer_amt_mod2 

no default 

Add a modiher to the distance keys 

pointer_amt_mod3 

no default 


You can assign keyboard keys to mouse button operations by specifying options 
in a X*pointerkeys hie. The following table lists the button operations, the 
5 X*pointerkeys functions that control them, and their default values: 

Table 5-6. Button Operation Functions 


Button Operation 

Function 

Default Key 

Perform button 1 operations 

pointer_buttonl_key 

keypad_* 

Perform button 2 operations 

pointer_button2_key 

keypad_/ 

Perform button 3 operations 

pointer_button3_key 

keypad_+ 

Perform button 4 operations 

pointer_button4_key 

keypad_- 

Perform button 5 operations 

pointer_button5_key 

keypad_7 
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You can change the mapping of buttons on the pointer by using options in the 
X*pointerkeys hie. The following table lists the X*pointerkeys functions that 
control button mapping and their default values. Like xmodmap and xset, these 
functions affect only the X pointer, not any extension input devices. 


Table 5-7. Button Mapping Functions 


Button Mapping 

Function 

Default Key 

Set button 1 value 

button_l_value 

1 

Set button 2 value 

button_2_value 

2 

Set button 3 value 

button_3_value 

3 

Set button 4 value 

button_4_value 

4 

Set button 5 value 

button_5_value 

5 


You can change the key sequence that exits the X Window System. Also, if you 
use both image and overlay planes, you can change the distance you must move 
the pointer before you switch planes. The following table lists these options, the 
X*pointerkeys functions that control them, and their default values: 


Table 5-8. Reset and Threshold Functions 


Option 

Function 

Default Key 

Exit the X Window System 

reset 

break 

Add a modifier to the exit key 

reset_modl 

control 

Add a modifier to the exit key 

reset_mod2 

left_shift 

Add a modifier to the exit key 

reset_mod3 

no default 

Set the threshold for changing 
between screens 

screen_change_amt 

30 pixels (0 if a graphics 
tablet is used) 


screen_change_amt is used only if your system is conhgured for more than 
one screen. screen_change_amt enables you to avoid switching from one 
screen to another if you accidentally run the pointer off the edge of the screen. 
screen_change_amt establishes a “distance threshold” that the pointer must 
exceed before the server switches screens. As the previous table shows, the default 
width of the threshold is 30 pixels, but acceptable values range from 0 to 255. 
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When a graphics tablet is used as the X pointer, the screen_change_amt dehnes 
an area at the left and right edges of the tablet surface that will be used to control 
screen changes. Moving the puck or stylus into the left or right area will cause 
the X server to switch to the previous or next screen. 


Table 5-9. Button Chording 


Option 

Function 

Default Action 

Turn button 
chording off or 

on 

button_chording 

On for devices with two buttons, off for 
devices with more than two buttons 


Button chording refers to the generation of a button-press by pressing two other 
buttons. If you have a two-button mouse, you can generate Button 3 by pressing 
both buttons together. With a three-button mouse, you can generate button 4 
by pressing the left and middle buttons together and button 5 by pressing the 
middle and right buttons together. See the button chording examples in the 
X*pointerkeys hie. 

You can also use the X*pointerkeys hie to conhgure pointer buttons so they are 
latched. When this feature is enabled, a button you press stays logically down 
until you press it again. See the example X*pointerkeys hie in /usr/lib/Xll 
for information on conhguring this functionality. 


Note 



The sample X*pointerkeys hie is placed in /usr/lib/Xll at 
install time. If you subsequently update your system, the 
X*pointerkeys hie in /usr/lib/Xll is not overwritten, and the 
sample hie is placed in /usr/newconf ig. 


Table 5-10. Specifying a Portion of a Tablet 


Option 

Function 

Default 

Use a subset of the 
tablet surface as the X 
pointer device 

tablet_subset_width 

tablet_subset_height 

tablet_subset_xorigin 

tablet_subset_yorigin 

disabled 
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If a tablet is used as the X pointer device, it may be desirable to use only a portion 
of the tablet surface. A rectangular subset of the surface may be specihed with 
these functions. The units are in millimeters from the upper left corner of the 
tablet surface. For example, if you want to use only an “A” size portion of a 
larger “B” size tablet, the following lines could be added to the X*pointerkeys 
hie: 


tablet_subset_xorigin 68 
tablet_subset_yorigin 40 
tablet_subset_width 296 

tablet_subset.height 216 


You can also use the X*pointerkeys hie to control screen switching behav¬ 
ior in multi-screen conhgurations. See the example X*pointerkeys hie in 
/usr/lib/Xll for an example of this functionality. 


Note 



The sample X*pointerkeys hie is placed in /usr/lib/Xll at 
install time. If you subsequently update your system, the 
X*pointerkeys hie in /usr/lib/Xll is not overwritten, and the 
sample hie is placed in /usr/newconf ig. 


Modifier Keys. You can select up to three keys from among the two f shift] keys, 
the two [Extend Char ] keys, and the [ctrQ key and use them each as modiher keys. A 
modiher key is a key that, when you hold it down and press another key, changes 
the meaning of that other key. 

Modiher keys in the X*pointerkeys hie have three functions: 

■ They specify that a certain operation can’t take place until they are pressed. 

■ They enable you to adjust the distance covered by the pointer during a 
movement operation. 

■ They enable you to change the key sequence that exits you from Xll. 

For example, you can overcome the problem in the last example by assigning 
the left [ Shift ") key as a modiher to the pointer direction keys. Now, to move the 
hpterm cursor to the right, you press as usual. To move the x server pointer 
to the right, you press left [shift") 
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Specifying Pointer Keys. To find out what key names are valid for the keyboard 
you are using, enter 

xmodmap -pk 

You may also use the default X Keysymbol names assigned to these keys by the 
X Server. 


Exampies. If you only have one keyboard and no mouse, and you can live with the 
default pointer key assignations, you don’t have to do anything else to configure 
your system for mouseless operation. To move the pointer to the left 10 pixels, 
you would press the CO key on the keypad. To press mouse button 1 you would 
press the 0 key on the keypad. 

However, suppose you wanted to move only one pixel to the left. Although 
the default value of pointer_mod2_aint is one pixel, no key is assigned to the 
modifier for that amount. Thus, you would need to edit the XOpointerkeys file 
(or create an X*pointerkeys) to include a line assigning one of the modifier keys 
to pointer_aint_mod2. The following line in XOpointerkeys assigns the left f shift ~) 
key to pointer_aint_mod2: 


###p ointerfunction key 
pointer_aint_mod2 left_shift 

Or suppose you wanted to set up your XOpointerkeys file so that you could move 
1, 10, 25, and 100 pixels. The following lines show one way to specify this: 


###pointer function 
pointer.amt_modl 
pointer.amt.mod2 
pointer, amt.mod3 
pointer.move 
pointer.modi, amt 
pointer.mod2.amt 
pointer.mods, amt 


key 

left.extend 
left.shift 
control 
1.pixels 
10.pixels 
25.pixels 
100.pixels 


With these lines in effect, one press of the (T) key on the keypad moves the pointer 
1 pixel to the left. Pressing the left f Extend ctiaT) and (T) moves the pointer 10 pixels 
to the left. Pressing left f shift] (T) moves the pointer 25 pixels to the left. And 
pressing CoT) CO moves the pointer 100 pixels to the left. 
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Or, take the case, previously mentioned, where you want to use the arrow keys 
for both text cursor and mouse pointer. You could insert the following lines in 
your XOpointerkeys hie: 


###pointer function 
pointer_key_modl 
pointer_left_key 
pointer_right_key 
pointer_up_key 
pointer_down_key 


key 

left_shift 

cursor_left 

cursor_right 

cursor_up 

cursor_down 


The above lines enable you to use the arrow keys for cursor movement, while 
using the shifted arrow keys for pointer movement. Note that only the left f shift] 
key (and not the right f shift] ) modihes the press of an arrow key from cursor to 
pointer movement. 


Now, suppose you want to use the arrow keys to operate the pointer, and you also 
need the arrow keys to control the cursor in an hpterm window. Furthermore, 
another application uses the shift-arrow key sequence to control its cursor. 


The easiest way to solve this dilemma is to call in another modiher. The following 
lines illustrate this. Compare them to the previous example. 


###pointer function 
pointer_key_modl 
pointer_key_mod2 
pointer_left_key 
pointer_right_key 
pointer_up_key 
pointer_down_key 


key 

left_shift 

left_extend 

cursor_left 

cursor_right 

cursor_up 

cursor_down 


In this example, 

■ Pressing the key moves the hpterm text cursor up. 

■ Pressing left [shift ~) 0 moves the cursor up in the program you frequently 
operate. 

■ Pressing left [shift ~) left [Extend Char] QJ moves the pointer up. 

Using a similar technique, you can also reassign the [Ctrl ] left f shift ] f Reset ~) sequence 
that aborts a session. You can specify the press of a single key or a combination 
of two, three, or four key presses. Just make sure that the key sequence you select 
isn’t something you’re going to type by accident. 
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Customizing Keyboard Input 

Besides remapping the mouse’s pointer and buttons to your keyboard, you can 
remap any key on the keyboard to any other key. 

Modifying Modifier Key Bindings with xmodmap 

To change the meaning of a particular key for a particular Xll session, or to 
initialize the X server with a completely different set of key mappings, use the 
xmodmap client. 


Note 



There are two keyboards available for Hewlett-Packard worksta¬ 
tions, the 46021 keyboard, and the C1429 keyboard. See “Using 
the Keyboards” for more information on using these keyboards 
and the differences between them. 
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The syntax for xmodmap is as 

follows: 

xmodmap [options) [{filename 

where [options) are: 

)] 

-display [host): [display) 

Specihes the host, display number, and screen to 

use. 

-help 

Displays a brief description of xmodmap options. 

-grammar 

Displays a brief description of the syntax for 
modihcation expressions. 

-verbose 

Prints log information as xmodmap executes. 

-quiet 

Turns off verbose logging. This is the default. 

-n 

Lists changes to key mappings without actually 
making those changes. 

-e [expression) 

Specihes a remapping expression to be executed. 

-pm, -p 

Prints the current modiher map to the standard 
output. This is the default. 

-pk 

Prints the current keymap table to the standard 
output. 

-pp 

Print the current pointer map to the standard 
output. 

- 

Specihes that the standard input should be used 
for the input hie. 

[filename) 

Specihes a particular key mapping hie to be used. 
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Specifying Key Remapping Expressions 


Whether you remap a single key “on the fly” with a command-line entry or 
install an entire new keyboard map file, you must use valid expressions in your 
specification, one expression for each remapping. 

A valid expression is any one of the following: 


Tabie 5-11. Vaiid xmodmap Expressions 


To do this . .. 

Use this expression . . . 

Assign a key symbol to 
a keycode 

keycode {keycode) = {keysym) 

Replace a key symbol 
expression with another. 

keysym {keysym) = {keysym) 

Clear all keys associated 
with a modifier key. 

clear {modifier) 

Add a key symbol to a 
modifier. 

add {modifier) = {keysym) 

Remove a key symbol 
from a modifier. 

remove {modifier) = {keysym) 


keycode Refers to the numerical value that uniquely identifies each key 

on a keyboard. Values may be in decimal, octal, or hexadecimal. 

Refers to the character symbol name associated with a keycode; 
for example, KP_Add. 

Specifies one of the eight modifier names: Shift, Control, Lock, 
Modi, Mod2, Mods, Mod4, and Mod5. 

On Hewlett-Packard keyboards, the lock modifier is set to the f caps Lock~) key. 
However, any of the modifiers can be associated with any valid key symbol. 
Additionally, you can associate more than one key symbol with a modifier (such 
as Lock = Shift_R and Lock = Shift_L), and you can associate more than one 
modifier with a key symbol (for example. Control = Caps_Lock and Lock = 
Caps_Lock). 


keysym 

{modifier) 
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For example, on a PC-style keyboard, you can press © to print a lowercase “d”, 
[ShifQ © to print a capital “D”, fAitXD~) to print something else, and [shift] c© 
© to print still something else. 

The xmodmap client gives you the power to change the meaning of any key at any 
time or to install a whole new key map for your keyboard. 


Examples 

Suppose you frequently press the [caps Lock ~) key at the most inopportune moments. 
You could remove the fcaps Lock") lock key from the lock modiher, swap it for the 
© key, then map the © key to the lock modiher. Do this by creating a little 
swapper hie that contains the following lines: 

!This file swaps the [Caps] key with the [FI] key. 


remove Lock = Caps_Lock 
keysym Caps_Lock = FI 
keysym FI = Caps_Lock 
add Lock = Caps_Lock 

Note the use of the ! in the hie to start a comment line. To put your “swapper” 
hie into effect, enter the following on the command line: 

xmodmap swapper 

If you use such a swapper hie, you should probably have an unswapper hie. The 
following hie enables you to swap back to the original keyboard mapping without 
having to exit Xll: 

!This file unswaps the [FI] key with the [Caps] key. 



remove Lock = Caps_Lock 
keycode 88 = FI 
keycode 55 = Caps_Lock 
add Lock = Caps_Lock 


Note the use of the hexadecimal values to reinitialize the keycodes to the proper 
key symbols. You put your “unswapper” hie into effect by entering the following 
command line: 


xmodmap unswapper 
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On a larger scale, you can change your current keyboard to a Dvorak keyboard 
by creating a file with the appropriate keyboard mappings. 

xmodmap .keymap 

Printing a Key Map 

The -pk option prints a list of the key mappings for the current keyboard. 

xmodmap -pk 

The list contains the keycode and up to four 2-part columns. The first column 
contains unmodified key values, the second column contains shifted key values, 
the third column contains meta ( [Extend Char] ) key values, and the fourth column 
contains shifted meta key values. Each column is in two parts: hexadecimal key 
symbol value, and key symbol name. 
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Using the Keyboards 

There are now two keyboards available for Hewlett-Packard workstations. In 
addition to the 46021 keyboard, a personal computer-style keyboard, C1429 
is also available. This new keyboard is also known as the “Enhanced Vectra” 
keyboard. 

Understanding the Keyboards 

If an application is reading input directly from the keyboard, it receives a keycode 
when a key is pressed. Equivalent keys on the two keyboards are those that 
generate the same keycode. If an equivalent key does not exist, there is no way 
to generate the corresponding keycode. 

In an X Window System environment, key codes are mapped into key symbols 
by the X library. The key symbols are stored in a keysym table. Application 
programs then reference these key symbols when accessing keys. 



Application 


Figure 5-1. Keycap, Keycode, and Keysym Relationships 



Equivalent keys are those keys that are mapped to the same key symbol. One 
advantage of this mapping is that if a key does not physically exist on a 
keyboard, its equivalent key symbol can be mapped to some other key through 
the corresponding keycode. 
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Default Keyboard Mapping 

The default keyboard mapping supplied with the X Window environment maps 
the C1429 keyboard to the same key symbols that are used for the 46021 
keyboard. This allows existing X client programs that expect to receive input 
from a 46021 keyboard to be used with either keyboard. However, the result is 
that some keys on the C1429 keyboard are mapped to key symbols that do not 
match the engravings on their keycaps. 


5 
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Equivalent Keys 

Some applications may expect to use keys that exist on one of the keyboards but 
not the other. In most cases, if a key does not exist on the keyboard in use, it is 
still possible to use some other key that is equivalent. To do this, it is necessary 
to know which keys are equivalent on the two keyboards. 

There are 14 keys on the C1429 keyboard that generate keycodes equivalent to 
keys on the 46021 keyboard, but have different engravings on the keycaps. Some 
have the same key symbol on both keyboards, while others do not. These C1429 
keys, their 46021 equivalents, and the corresponding symbol names are shown in 
the following table. 


Table 5-12. 


C1429 Keycap 

46021 Keycap 

Default Key Symbol 

XPCmodmap Symbol 


blank 1 

F9 

F9 

(m) 

blank2 

FIO 

FIO 

(fT3 

blanks 

Fll 

Fll 


blank4 

F12 

F12 

(Print Screen/SysRq ) 

(jVlenuJ 

Menu 

Print 

(Scroll Lock) 

(stop) 

Cancel 

Scroll_Lock 

(Pause/Break) 

(Break/Reset) 

Break/Reset 

Pause/Break 

(Page Up ) 


Prior 

Prior 

(Num Lock ) 

(System/User) 

System/User 

Num_Lock 

lEnd] 

[SelectJ 

Select 

End 

(Page Down ) 


Next 

Next 

(Enter) 

(Return ) 

Return 

Return 

(^3 (left) 

(Extend Char) (left) 

Meta_L 

Alt_L 

(^3 (right) 

(Extend Char) (right) 

Meta_R 

Alt_R 
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Changing Key Mapping 

X provides the means to change the key mapping, if you so desire. One way 
to accomplish this is by running the xmodmap client program. Hewlett-Packard 
provides two hies in the directory /usr/lib/Xll to use with xmodmap. One, 
XPCmodmap, causes xmodmap to change the key mapping to match the keycap 
engravings on the C1429 keyboard. The other, XHPmodmap, causes xmodmap to 
change the key mapping to match the keycap engravings on the 46021 keyboard, 
which are the defaults. This allows either keyboard to be used with applications 
that expect the other keyboard, although only one mapping can be used at any 
given time. When the mapping is changed, the X Server notihes all clients that 
are executing at that time. Some clients may load the new mapping from the 
server right away, but others may have to be restarted in order to recognize the 
new mapping. For more information about using the xmodmap client, see the 
xmodmap man page. 

C1429 Keyboard 

Execute the following command to change the mapping of the keys shown above 
to match the engravings on the C1429 keycaps. 

/usr/bin/X11/xmodmap /usr/lib/Xll/XPCmodmap 

46021 Keyboard 

Execute the following command to change the mapping to match the 46021 
keyboard. 

/usr/bin/X11/xmodmap /usr/lib/Xll/XHPmodmap 
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Comparing the Keyboards 


The 46021 keyboard has 107 keys, while the C1429 keyboard has 101 keys. There 
are 7 keys on the 46021 keyboard whose keycodes cannot be generated by any 
key on the C1429 keyboard, and whose key symbols cannot be generated when 
using the default keymap for the C1429 keyboard. The missing keys are: 

■ [ clear Line ] 

■ [ clear Display J 

■ [ insert Line J 

■ [ Delete Line ] 

■ [ Print/Enter J 

■ Q (on number pad) 

■ [Tab ~) (on number pad) 

Q and [Tab ~) exist elsewhere on the C1429 keyboard, and the others are not needed 
by most applications. Applications that do need one or more of them must assign 
their key symbols to the keycodes of existing keys. The xmodmap client can be 
used to determine the keycode-to-key symbol mapping of existing keys, and it 
can also be used to assign the key symbol to the desired keycode. These keys 
use HP specihc key symbol names whose correct spelling can be found in the hie 
/usr/lib/Xll/XKeysymDB. 

The right [ Ctrl ') key on the C1429 keyboard generates a keycode that has no 
equivalent on the 46021 keyboard. This key has the same effect as the left f ctrl ] 
key by default. 

Keys not mentioned above exist on both keyboards, and have the same key 
symbols. 
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PowerShade: Enhanced 3D Rendering in 
Software 


PowerShade is a software product that allows lighting, shading, and hidden- 
surface removal. It offers the capability for both surface rendering and volumetric 
rendering. (Volumetric rendering is available on supported devices only.) 

PowerShade is not supported on the GRX or on any grayscale version of the 
Models 705, 710, 715 or 725. (See your Owner’s Guide for more details on HP 
9000 workstations.) 

Instructions on how to install PowerShade are included in this document. Once 
PowerShade has been installed, any 9.x applications that use PowerShade will 
run on the HP-UX 10.20 system. 

Because PowerShade functionality is API-independent, it is fully supported 
by Starbase, HP-PHIGS, and HP PEX. For more information, refer to the 
appropriate API manual set. 
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Compatibility Considerations 

You should consider the following information before you run an HP-UX 9.x 
application on an HP-UX 10.a; system. This applies to applications that use HP 
PEXlib, Starbase, or HP-PHIGS graphics libraries. 

■ If your HP-UX 9.a; application uses PowerShade functionality, you need to 
make sure you have PowerShade installed on your HP-UX 10.a; system for it to 
run. To do this, use swlist to conhrm that the PowerShade hleset has been 
installed on your system. 

■ If your HP-UX 9.a; application uses HP VMX and it is designed to send output 
to an X terminal, you need to have PowerShade installed on your HP-UX 
10.a; system. Note that even though some graphics devices automatically have 
PowerShade capabilities, you still need to have PowerShade installed in order 
to output graphics to a remote X terminal. 

As part of the transition to only supporting 3D computer graphics within the X 
Windows environment, the Release 10.a; versions of Starbase no longer support 
input directly from interactive devices such as a keyboard, mouse, trackball, 
digitizing tablet, button box, knob box, or similar devices. Applications should 
request input of this type through the X server. 

The result of directly accessing an interactive input device from Starbase in 
Release 10.a; is undehned. If your application reads input directly from a mouse, 
keyboard, etc., using Starbase input calls, you should modify that application to 
use Xlib calls to read data from these devices. (This statement does not apply 
to HP-PEXlib since that API does not include input mechanisms. The PEXlib 
programmer should already be using Xlib for input.) 

Starbase applications that are linked with HP-UX 9.x shared or archived libraries 
may see different input handling behavior when run on an HP-UX 10.a; system. 

Versions of HP-UX prior to Release 10.a; will continue to support direct input as 
before. Hewlett-Packard documentation will continue to describe input calls for 
Starbase because these manuals are also used with versions of these APIs that 
support direct input. 
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Re-Installing PowerShade 

PowerShade comes bundled with the HP-UX operating system (10.30 and later), 
but in case you ever need to re-install it, do the following: 

1. Follow the instructions in the HP-UX manual Managing HP-UX Software with 
SD-UX to install software (using the /usr/sbin/swinstall process). 

2. Select the PowerShade product for installation. 


HP Series 700 Graphics Performance 

The following information is intended to help application developers understand 
graphics performance on the HP 9000 Series 700 family of graphics workstations. 

The VRX family of graphics devices (for example, PersonalVRX and TurboVRX) 
have not changed in any signihcant way with the 9.0 or later releases. Therefore, 
the information presented here should not be applied to these devices. See the 
HP- UX Starhase Device Drivers Manual for more information on the VRX family. 


Note 



Important! If you are not certain what devices are running on 
your workstation, you can obtain specihc information about your 
graphics device (product name, device driver and capabilities 
supported) by executing: 

/opt/graphics/common/bin/graphinfo 

For a detailed description of this utility, see the manpage on 
graphinfo(lG) in the Starhase Reference Manual. 


HP has optimized graphics performance for many typical cases. The data in 
the following table describes how to get the maximum performance for polygon, 
polyline, and polymarker primitives. In addition to primitive-specihc data, there 
is also data regarding general rendering conditions and window conhgurations. 
It is important to note that these general rendering conditions and window 
conhgurations must be considered in addition to the primitive-specihc conditions 
in order to make an accurate analysis of performance. 
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Maximum performance can be achieved using features listed under “Performance 
Optimized For” in the following table. Any combination of these features can 
be used for optimal performance. In general, performance will slowly degrade as 
more of these features are used. (For example, rendering with seven directional 
light sources is slower than with only a single one.) 

Other features are available (listed as “Factors Affecting Performance”) but 
should be used with discretion as performance is signihcantly slower if even one 
of these features is used. 


Note 



The following table was complete as of the date of publication 
of this document. For updated table entries that provide more 
performance/optimization information, see the online release 
notes in /opt/graphics/starbase/PERF_NOTES. 


Table 6-1. Optimized vs. Normal 3D Performance 


Performance Optimized For 

Factors Affecting Performance 

Rendering Conditions 

■ Up to 15 directional lights plus ambient. 

■ Directional or positional eyepoint. 

■ Specular reflections on or off. 

■ Back face cull on or off, and with or 
without supplied geometric normal. 

■ Clip check trivial accept or reject. 

■ Perspective or parallel projections. 

■ Isotropic modeling matrix (that is, 
angle-preserving). 

■ CMAP_FULL. 

■ Positional light sources. 

■ Picking. 

■ Heavily interleaved modal calls: 

double_buffer, 
vertex_format, 
shade_mode, 
hidden_surface. 

■ Frequent attribute changes: 

fill_color. 


6-4 PowerShade: Enhanced 3D Rendering in Software 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


Table 6-1. Optimized vs. Normal 3D Performance (continued) 


Performance Optimized For 

Factors Affecting Performance 

Window Conditions 

■ Unobscured or obscured by overlay 
windows only. 

■ Single HP PEXlib renderer per window, 
or single Starbase gopen per window. 

■ Obscured window. 

■ Backing Store. 

■ Multiple renderers, gopens. 

■ Heavily interleaving Xlib calls with 3D 
API operations. 

Polygon Primitives 

■ Primitives with normals per vertex and 
lighting on, or primitives with RGB 
color data per vertex and lighting off. 

■ HP PEXlib PEXFillAreaMithData, 
PEXSetOfFillAreaSets, 
PEXFillAreaSetMithData, 
PEXTriangleStrip. 

■ Z-buffering disable. 

■ Depth cue turned off. 

■ Starbase polygonSd, 
polygon_with._data3d. 

■ Starbase triangular_strip, 
triangular_strip_with._data, and 
polyh.edron_with._dat a. 

■ HP-PHIGS (one set only) 

fill_area_set_3_with_data. 

■ HP-PHIGS 

triangle_strip_3_with_data 

■ Normals may be unit length or not. 

■ With or without move/draw edge flags, 
with edging off or on. 

■ Convex geometry. 

■ Fewer Starbase calls with more vertices 
per call (up to 128 vertices). 

■ Geometric normals with and without 
vertex data. 

■ Extra data actually used per vertex (for 
example, RGB and normals per vertex 
both used, alpha per vertex, etc.). 

■ More than 64 vertices in a polygon. 

■ Fill area set primitives with greater 
than one set. 

■ Starbase partial polygons. 

■ 2D polygons and Rll areas or fill-area 
sets. 

■ Device Coordinate (DC) Polygons. 

■ Edged polygons. 



PowerShade: Enhanced 3D Rendering in Software 6-5 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


Table 6-1. Optimized vs. Normal 3D Performance (continued) 


Performance Optimized For 

Factors Affecting Performance 

Polyline Primitives 

■ Extra data per vertex which is not used 
(that is, skipped). 

■ Z-buIfering disabled. 

■ HP PEXlib, Starbase, or HP-PHIGS 
polyline primitives. 

■ 2D or 3D transforms. 

■ Depth cue turned off 

■ User-supplied move/draw flags present 
or not present. 

■ CMAP_FULL or CMAP_ISFORMAL (except 

CRX where CMAP_ISFORMAL is faster). 

■ Fewer polylines with more vectors in 
each polyline. 

■ Z-buffering in software using 

PowerShade (for example, on GRX-24, 
Internal Golor Graphics). 

■ Non-polyline vector primitives (for 
example, stroked text, IISFT_OUTLIISFE 
polygons, EDGED polygons). 

■ CMAP_M0ISF0T0ISFIC. 

■ User-supplied RGB, indirect color, or 
intensity per vertex. 

■ Frequent line color or line type changes. 

Polymarker Primitives 

■ Z-buffering disabled. 

■ HP PEXlib, Starbase, or HP-PHIGS 
polymarker primitives. 

■ 2D or 3D transforms. 

■ Depth cue turned off 

■ User-supplied move/draw flags present 
or not present. 

■ CMAP_FULL or CMAP_ISFORMAL. 

■ Z-buffering in software using 

PowerShade (for example, on GRX-24, 
Internal Golor Graphics). 

■ CMAP_M0ISF0T0ISFIC (Starbase). 

■ User-supplied RGB, indirect color, or 
intensity per vertex. 

■ Pseudo color mapping method 
(HP-PHIGS) 
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Miscellaneous Topics 


3D Thread-Safing 

General Information 

For HP-UX release 10.30 and later, Hewlett-Packard’s 3D graphics APIs are 
supported in multi-threaded applications (using POSIX threads). However, 
these libraries are thread-restricted and can be accessed only from a single 
dedicated thread of a multi-threaded program. This documentation is not a 
tutorial on threads programming or multiprocessing application issues. For more, 
and general, information about the use of POSIX threads, consult the HP-UX 
documentation set. Further restrictions on use of these APIs in multi-threaded 
programs are: 

■ The 3D graphics libraries support kernel threads only (libpthread); they do 
not support the DCF user threads package (libcma). 

■ If your multi-threaded application uses both 3D graphics and Xll, or 3D 
graphics and Motif routines, then the 3D graphics routine calls are restricted 
to the same single thread as the Xll or Motif routine calls. This restriction 
applies to Xll or Motif routines in any of the libraries: libXll, libXext, 
libXhpll, libXi, libXt, and libXm. 
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■ Miscellaneous signal handling restrictions. 

SIGALRM See the “SIGALRM Details” section below for more 

information. 

SIGCHLD A multi-threaded application should not change the 

SIGCHLD action during the short periods when the 
graphics libraries are starting the Graphics Resource 
Manager daemon (“grmd”) or terminating the Starbase 
input daemon. See the “SIGCHLD and the GRM 
Daemon” and “SIGCHLD and the Starbase Input 
Daemon” sections below for more information. 

SIGPIPE A graphics application that uses an HP VISUALIZE- 

48/48XP device with hardware texture mapping, or 
an HP-PHIGS application that does graphics input 
should not change the SIGPIPE signal action. See the 
“SIGPIPE Details” section below for more information. 

Other Threads-Related Information 

1. All of the 3D graphics functions are cancellation points. 

2. None of the 3D graphics functions are async-cancel safe. 

3. None of the 3D graphics functions are async-signal safe. 

4. None of the 3D graphics functions are fork-safe, i.e., they cannot be called by 
a child process after a fork(2), but before an exec(2). 


Note 



Calls to 3D graphics functions between a fork and an exec have 
never been supported. 


5. There is one situation in which graphics behavior may be different for multi¬ 
threaded versus single-threaded programs. In a multi-threaded Starbase 
application, a call to gopen(3g) a serial plotter might not return if the plotter 
does not respond (e.g., if the plotter is turned off). In this multi-threaded 
case, the graphics thread could wait forever for the device. Single-threaded 
behavior in this case is for the gopen(3g) to timeout and return an error. 
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SIGALRM Details 


The Starbase library temporarily sets a SIGALRM signal handler and uses 
setitimer(2) to start a timer in two situations: 

1. To set a timeout for device access in calls to gopen(3g) for a serial plotter. 

2. To set a maximum time to wait for an event in calls to await_event(3g), 
read_choice_event(3g), read_locator_event(3g), and 
intread_locator_event(3g). 

Calls to the above Starbase functions should not be made in one thread while at 
the same time another thread performs any of the following: 

■ Changes the SIGALRM signal action; 

■ Calls sigwait(2), selecting the SIGALRM signal; 

■ Uses setitimer(2); 

■ Uses timer_settime(2) to set a timer which will generate a SIGALRM signal. 
Possible consequences of violating these non-concurrency restrictions are: 

■ The Starbase function call never returns; 

■ The wait for a plotter response or for an event is shorter than it should be; 

■ Alarm signals from timers set in other threads do not have the desired effect 
(because the graphics signal handler is in place); 

■ Unpredictable results due to concurrent use of the process-wide timer provided 

by setitimer(2). 

SIGCHLD and the GRM Daemon 

The Graphics Resource Manager Daemon (grmd) is started when the Xll Server 
is started. In normal operation, a Starbase, HP PEX, or HP-PHIGS application 
will not start the daemon, and so will not be affected by the SIGCHLD manipulation 
that occurs as part of that startup (see below). However, if the grmd dies for some 
reason, the graphics libraries will restart the daemon whenever they need shared 
memory. This can occur in the following instances: 

■ During calls to the following Starbase functions: gopen(3g), gcIose(3g), 
enable_events(3g), disable_events(3g), set_signals(3g), and track(3g). 

■ When HP-PHIGS and HP PEX initialize their output devices. 

■ When HP-PHIGS input is initialized. 

■ During calls to glXCreateContext or gIXMakeCurrent. 
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When the grmd is started, the sequence of events is: 

1. Set the SIGCHLD action to SIG_DFL, saving the old action. 

2. fork(2) and exec(2) an intermediate process, which is the grmd’s parent. 

3. Call waitpid(2) to wait for the intermediate process to die (after starting the 
grm daemon). 

4. Restore the saved SIGCHLD action. 

Between the time that the graphics thread sets the SIGCHLD action to SIG_DFL 
and restores the saved action, other threads should not change the SIGCHLD action 
by calls to sigaction(2), sigvector(2), signal(2), sigset(2), or sigwait(2). 

The following are possible consequences of such concurrency: 

■ If the concurrent operation sets the SIGCHLD action to SIG_IGN, the graphics 
thread could hang. 

■ If the concurrent operation installs a signal handler for SIGCHLD, that handler 
may be invoked when the graphics child process dies. 

■ A call to sigwait might return in response to the death of the graphics child 
process. 

■ Any SIGCHLD action concurrently set by the application could be overwritten 
when the graphics thread restores the saved SIGCHLD action. 

SIGCHLD and the Starbase Input Daemon 

The Starbase input daemon is started whenever tracking or event monitoring is 
enabled. When tracking and event monitoring are turned off or when the output 
device is closed, Starbase terminates the daemon, using this process: 

1. Set the SIGCHLD action to SIG_DFL, saving the old action. 

2. Send a message to the input daemon asking it to terminate. 

3. Call waitpid(2) to wait for the daemon’s death. 

4. Restore the saved SIGCHLD action. 

In a Starbase application using tracking or events, a non-graphics thread should 
not set the SIGCHLD action by calls to sigaction(2), sigvector(2), signal(2), 
sigset(2), or sigwait(2) concurrently with calls in the graphics thread to 
track(3g), track_off(3g), disable_events(3g), or gcIose(3g). 

Possible consequences of violating this restriction are the same as those listed 
above for the grmd daemon. 
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SIGPIPE Details 


The graphics libraries start a daemon process and communicate with that process 
via sockets in two situations: 

■ For hardware texture mapping on an HP VlsUALlZE-48/-48XP display using 
the Texture Interrupt Manager Daemon (timd). 

■ For HP-PHIGS input using the PHIGS daemon (phg_daemon). 

When starting either of these daemons, the graphics library permanently sets the 
SIGPIPE action to SIG_IGI. This prevents the terminating SIGPIPE signal from 
being delivered to the process should the daemon die abnormally. 

If your application changes the SIGPIPE action to SIG_DFL or to a specihc 
handler, an abnormal death of either timd or phg_daemon will result in a SIGPIPE 
signal being delivered to the process when the graphics library next attempts 
to communicate with the daemon. If the action is SIG_DFL, the process will 
terminate. 
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Gamma Correction 


Gamma correction is used to alter hardware colormaps to compensate for the 
non-linearities of CRT monitors. Gamma correction can be used to improve the 
“ropy” or modulated appearance of antialiased lines. Gamma correction is also 
used to improve the appearance of shaded graphics images as well as scanned 
photographic images that have not already been gamma corrected. 

Why Is Gamma Correction Needed? 

The intensity of light generated by a conventional monitor is non-linear with 
respect to the signal applied. The intensity output is approximately equal to the 
applied voltage raised to a power. This power is referred to as the gamma of the 
monitor. Stated mathematically, 

intensity = voltage^"'™™^^ 

For example, the gamma value of a properly adjusted monitor is usually between 
2.35 and 2.55. Ideally, to produce an image that is 50% intensity, you would 
specify color values that are 50% of the maximum value. However, a monitor with 
a gamma of 2.4 would generate an intensity that is only 19% of the maximum 
intensity (0.5^’'^ = 0.19). 

The intensity principle is illustrated in the following test patterns. The pattern 
on the left has an area with exactly 50% brightness directly next to an area 
of horizontal stripes that alternate 100% brightness with 0% brightness. From 
a distance, the intensity of each area should be about the same. The middle 
pattern is basically the same, but just a little dimmer. 



Figure 7-1. Gamma-Correction Test Pattern 
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Once the brightness and contrast of your monitor are adjusted properly (see 
below), you can run the gamma correction tool (also described below) to see its 
effect on the test patterns above. 

Monitor Brightness and Contrast 

Often, the brightness control on a monitor is boosted to compensate for images 
that look dim due to a lack of gamma correction. Before applying gamma 
correction, the monitor brightness should be adjusted so a blank screen looks 
black in typical viewing conditions. Next, display a picture that is predominantly 
black, and adjust the brightness so that the monitor reproduces true black on 
the screen. The brightness should be adjusted to the threshold where it is not so 
far down as to “swallow” codes greater than the black code, but not so high that 
the picture sits on a “pedestal” of dark grey. 

When the critical point is reached, leave the brightness control in that position. 
Then set contrast to suit your preference for display intensity. 

How to run the Gamma Correction Tool 

Note that you do not need to have superuser privileges to use the gamma 
correction tool. 

To use the gamma correction tool, execute the following command: 

/opt/graphics/common/bin/gamma 

If you get the error “Can’t open display”, set the DISPLAY environment 
variable by executing this command: 

export DISPLAY=:0.0 
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How to Install the Gamma Icon Into your CDE Front Panel 

In a terminal window, go to your home directory and follow these steps 

1. Execute this command: 

cp /opt/graphics/common/icons/Gamma.* $H0ME/.dt/icons/ 

2. Select the Applications Icon on the CDE Eront Panel: 



Figure 7-2. 

3. Double-click the “Desktop_Apps” button: 
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De skt op_App s 


Figure 7-3. 

4. Double click the “Create Action” button: 


Create Action 


Figure 7-4. 
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Use the following steps to fill in the “Create Action” form. 

1. Enter Gamma in the “Action Name” window. 

2. Enter /opt/graphics/common/bin/gamma in the “Command When Action is 
Opened” window. 

3. Click “Eind Set ...” and double click on the .dt/icons directory under your 
home directory. 
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4. Select the “Gamma Icon” so your form appears as shown below: 


J 


Action Name (Icon Label): 


Action Icons: 


0 


Find Set.. 
Edit Icon. 


Command When Action Is Opened (Double-clicked): 


Help Text For Action Icon: 


Window Type: Graphical (X-Window) 


Advanced 


Figure 7-5. 
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Once you have filled in the “Create Actions” form, select “Save” from the File 
menu and follow these steps: 

1. Click the Home Folder Icon on the CDF Front Panel, and then, click the 
up-arrow above the “Home Folder Icon” to display the sub-menu. 


fMmmwmWmmmmi 

Figure 7-6. 

2. Drag the Gamma Icon from File Manager onto “Install Icon”. 


Figure 7-7. 
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3. Your “Home Folder” will should look similar to this: 




Figure 7-8. 

If you would prefer to have the “Gamma Icon” in the Main Panel, double-click 
the right mouse button. 
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Using the Gamma Correction Tool 


Gamma Correction 

1.0 = No Gamma Correction ; 1.7 = Recommended Vaiue 

1.00 

Scope of Gamma Correction: 

Aii Windows 

Seiect A Window 

. Mo<yi'y 

Save as Screen Defauit 
Remove Screen Defauit 
OK Cancei Heip 

Figure 7-9. Gamma-Correction Tooi 


Gamma Vaiue Siider 

The gamma value represents a power, so a value of 1.0 is the same as no gamma 7 
correction. Although the actual measured gamma value of most monitors is 
over 2.0, a gamma value of 1.7 is recommended since most applications have 
historically compensated for a lack of gamma correction by simply making the 
entire image brighter. 
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Scope of Gamma Correction 


This area of the “Gamma correction” window allows you to select all windows to 
receive gamma correction or only a selected group of windows. Once you have 
made your selection, you can then save it as the default setting. 

Selecting All Windows. To select all windows for gamma correction, single click 
on the “All Windows” button. Note that selecting this button applies gamma 
correction to the colormaps for all windows and will cause images, graphics, and 
user interfaces to all use the same specihed gamma value. 

Selecting Individual Windows. When you press “Select A Window,” the cursor 
changes to a crosshair. Next, move the crosshair into the window you wish to 
modify and click the left mouse button. You will be able to control the gamma 
value for the colormap associated with the selected window. 

If the colormap used by the selected window is also used by other windows, their 
appearance will change along with the actual window you selected. 

If the only colormap used by the selected window is the default colormap, then 
you will need to check the “Modify Default Colormap” box as well. Note that 
modifying the default colormap will change the appearance of many windows and 
user-interface elements. 

Save as Screen Default. When you select the “Save as Screen Default” button, 
the current gamma value will be saved in the appropriate X screens hie 
(XOscreens for screen 0, Xlscreens for screen 1, etc.). Note that, when you 
quit CDE and X windows, the value you save in the X screens hie will be used 
the next time X is started. 

Since the X screens hie is a system resource, your system administrator 
determines who has permission to modify that hie. 

Remove Screen Default. If you select the “Remove Screen Default” button, the 
default gamma value saved in the X screens hie will be removed and the gamma 
value for all windows will be reset to 1.0. 

This option also requires appropriate permissions to modify the X screens hie. 
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HP CDE and HP VUE 


Hewlett-Packard is in the process of a transition to a standard user environment. 
Two user environments were shipped with HP-UX 10.20: HP VUE and HP CDE 
(Common Desktop Environment). Starting with HP-UX 10.20, HP CDE was be 
the default user environment, and although HP VUE was still be available with 
HP-UX 10.20, but is not be available in HP-UX 10.20 releases. See the Common 
Desktop Environment User’s Guide for more information on HP CDE. 

Erom a 3D graphics point of view, the change in user environments should have 
no effect. 


Shared Memory Usage 

Graphics processes use shared memory to access data pertaining to the display 
device and the Xll resources created by the server (for example, color maps, 
cursors, etc.). The Xll server initiates an independent process called the 
Graphics Resource Manager (GRM) to manage these resources among graphics 
processes. One problem encountered with GRM shared memory is that it may 
not be large enough to run some applications. 

HP PEX, Starbase, and HP-PHIGS use GRM shared memory for VM double¬ 
buffering. If your application is running on a low-end graphics system (for exam¬ 
ple, an HP 710 or 712), you set the environment variable HP_VM_D0UBLE_BUFFER 
(or SB_710_VM_DB), and you have several large double-buffered windows open 
simultaneously, then your application could use up available GRM shared mem¬ 
ory. If you encounter a dbuff er_switch error message while using VM double¬ 
buffering, you may have encountered this problem. 

You can prevent this problem by changing with Shared Memory size through 
HP-UX’s SAM (System Administration Manager) program. 
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Reference Documentation 


You may find the following documentation helpful when using HP graphics 
products: 

■ For Starbase programming 

□ Starbase Reference 

□ Starbase Graphics Techniques 

□ HP-UX Starbase Device Drivers Manual 

□ Starbase Technical Addendum for HP-UX 10.20 

□ Starbase Display Tist Programmer’s Manual 

□ Fast Alpha/Font Manager Programmer’s Manual 

■ For PEXlib programming 

□ PEXlib Programming Manual 

□ PEXlib Reference Manual 

□ HP PEX Implementation and Programming Supplement 

■ For HP-PHIGS programming 

□ HP-PHIGS C and Fortran Binding Reference 

□ HP-PHIGS Graphics Techniques 

□ HP-PHIGS Workstation Characteristics and Implementation 

□ HP-PHIGS Technical Addendum for HP-UX 10.20 

■ For installing products 

□ HP-UX Reference 

□ System Administration Tasks 

□ Imstalling and Updating HP-UX 
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Reference Pages 


This section contains two reference pages: X Windows and X Server. 
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X Windows 

A portable, network-transparent window system. 

Synopsis 

The X Window System is a network-transparent window system developed at 
MIT which runs on a wide range of computing and graphics machines. It should 
be relatively straightforward to build the MIT software distribution on most 
ANSI C-compliant and POSIX-compliant systems. Commercial implementations 
are also available for a wide range of platforms. 

The X Consortium requests that the following names be used when referring to 
this software: 

■ X 

■ X Window System 

■ X Version 11 

■ X Window System, Version 11 

■ Xll 

X Window System is a trademark of the Massachusetts Institute of Technology. 

Description 

X Window System servers run on computers with bit-mapped displays. The 
server distributes user input to and accepts output requests from various client 
programs through a variety of different interprocess communication channels. 
Although the most common case is for the client programs to be running on the 
same machine as the server, clients can be run transparently from other machines 
(including machines with different architectures and operating systems) as well. 

X supports overlapping hierarchical subwindows and text and graphics opera¬ 
tions, on both monochrome and color displays. For a full explanation of the 
functions that are available, refer to: 

■ XUb - C Language X Interface, 

■ The X Window System Protocol specihcation, 

■ X Toolkit Intrinsics - C Language Interface, and 

■ The various Toolkit documents. 
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The number of programs that use X is quite large. Programs provided in the 
core MIT distribution include: a terminal emulator (xterm), a window manager 
(twm), a display manager (xdm), a console redirect program (xconsole), mail 
managing utilities (xmh and xbiff), a manual page browser (xman), a bitmap 
editor (bitmap), a resource editor (editres), a ditroff previewer (xditview), 
access control programs (xauth and xhost), user preference setting programs 
(xrdb, xcmsdb, xset, xsetroot, xstdcmap, and xmodmap), a load monitor 
(xload), clocks (xclock and oclock), a font displayer (xfd), utilities for listing 
information about fonts, windows, and displays (xlsfonts, xfontsel, xwininfo, 
xlsclients, xdpyinfo, and xprop), a diagnostic for seeing what events are 
generated and when (xev), screen image manipulation utilities (xwd, xwud, xpr, 
and xmag), and various demos (xeyes, ico, xgc, xllperf, etc.). 

Hewlett-Packard provides a graphical user environment called The Common 
Desktop Environment (CDE). HP CDE is the user interface, enabling the user to 
control a workstation by directly manipulating graphic objects instead of typing 
commands on a command-line prompt. See the CDE User’s Guide for complete 
information on HP CDE. 

Hewlett-Packard does not provide or support the entire core MIT distribution. 
Many of these programs or clients are sample implementations, or perform tasks 
that are accomplished by other clients in Hewlett-Packard’s Common Desktop 
Environment. The primary differences between the core MIT distribution and 
the Hewlett-Packard Xll release are listed below: 

Terminal Emulation Although hpterm is the primary terminal emulator, 

xterm is also provided and supported. 

twm is replaced by mwm and dtwm. 

xdm is replaced by an enhanced version called dtlogin. 
bitmap is replaced by dticon. 

This is handled by the terminal emulation option “-fn 
override”, xfd is supplied but not supported. 

Demos Obtained from the InterWorks users group. 

A number of unsupported core MIT clients and miscellaneous utilities are 
provided in /usr/contrib/bin. In addition, the entire core MIT distribution, 
compiled for Hewlett-Packard platforms, can be obtained from HP’s users group 
InterWorks for a nominal fee. 


Window Management 
Display Manager 
Bitmap Editing 
Eont Display 
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Many other utilities, window managers, games, toolkits, etc. are included as user- 
contributed software in the MIT distribution, or are available using anonymous 
ftp on the Internet. See your site administrator for details. 

Starting Up 

Normally, the X Window System is started on Hewlett-Packard systems by 
dtlogin, which is an enhanced version of the MIT client xdm. dtlogin can 
be used to bring up a full CDE session, a light CDE session, or a fail-safe session 
that uses no other part of CDE. If dtlogin is not used, xinit may be used with 
xllstart. See the reference pages for these functions for more information. 
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Display Names 

From the user’s perspective, every X server has a display name of the form: 
hostname : displaynumher . screennumber 

This information is used by the application to determine how it should connect 
to the server and which screen it should use by default (on displays with multiple 
monitors): 

hostname The hostname specihes the name of the machine to which the 

display is physically connected. If the hostname is not given, 
the most efficient way of communicating to a server on the same 
machine will be used. 


displaynumher The phrase “display” is usually used to refer to the collection 
of monitors that share a common keyboard and pointer (mouse, 
tablet, etc.). Most workstations tend to only have one keyboard, 
and therefore, only one display. Larger, multi-user systems, 
however, will frequently have several displays so that more than 
one person can be doing graphics work at once. To avoid 
confusion, each display on a machine is assigned a display number 
(beginning at 0) when the X server for that display is started. 
The display number must always be given in a display name. 

screennumber Some displays share a single keyboard and pointer among two or 
more monitors. Since each monitor has its own set of windows, 
each screen is assigned a screen number (beginning at 0) when 
the X server for that display is started. If the screen number is 
not given, then screen 0 will be used. 

On POSIX systems, the default display name is stored in your DISPLAY 
environment variable. This variable is set automatically by the xterm terminal 
emulator. However, when you log into another machine on a network, you’ll need 
to set DISPLAY by hand to point to your display. For example, 

"/, setenv DISPLAY myws:0 (C Shell) 

$ DISPLAY=myws : 0; export DISPLAY (Korn Shell) 

The xon script can be used to start an X program on a remote machine; it 
automatically sets the DISPLAY variable correctly. 
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Finally, most X programs accept a command line option of “-display display- 
name” to temporarily override the contents of DISPLAY. This is most commonly 
used to pop windows on another person’s screen or as part of a “remote shell” 
command to start an xterm pointing back to your display. For example, 

$ xload -display joeswsrO -geometry 100x100+0+0 
$ rsh big xterm -display myws:0 -Is </dev/null & 

X servers listen for connections on a variety of different communications channels 
(network byte streams, shared memory, etc.). Since there can be more than one 
way of contacting a given server, the hostname part of the display name is used 
to determine the type of channel (also called a transport layer) to be used. X 
servers generally support the following types of connections: 

local The hostname part of the display name should be the empty string. 

For example: “:0”, “:1”, or “:0.1”. The most efficient local 
transport is chosen. 

TCP/IP The hostname part of the display name should be the server ma¬ 
chine’s IP address name. Full Internet names, abbreviated names, 
and IP addresses are all allowed. For example: expo. Ics .mit. edu: 0, 
expo:0, 18.30.0.212:0, bigmachine:1,and hydra:0.1. 

Access Control 

An X server can use several types of access control. Mechanisms provided in 
Release 5 are: 

■ Host Access (simple host-based access control); 

■ MIT-MAGIC-COOKIE-1 (shared plain-text “cookies”); 

■ XDM-AUTHORIZATION-1 (secure DES based private-keys); and 

■ SUN-DES-1 (based on Sun’s secure rpc system). 

dtlogin/xdm initializes access control for the server, and also places authorization 
information in a hie accessible to the user. Normally, the list of hosts from which 
connections are always accepted should be empty, so that only clients with are 
explicitly authorized can connect to the display. When you add entries to the host 
list (with xhost), the server no longer performs any authorization on connections 
from those machines. Be careful with this. 

The hie from which Xlib extracts authorization data can be specihed with the 
environment variable XAUTHORITY, and defaults to the hie .Xauthority in the 
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home directory, dtlogin/xdm uses $H0ME/.Xauthority and will create it or 
merge in authorization records if it already exists when a user logs in. 

If you use several machines, and share a common home directory across all of 
the machines by means of a network hie system, then you never really have to 
worry about authorization hies; the system should work correctly by default. 
Otherwise, as the authorization hies are machine-independent, you can simply 
copy the hies to share them. To manage authorization hies, use xauth. This 
program allows you to extract records and insert them into other hies. Using this, 
you can send authorization to remote machines when you log in, if the remote 
machine does not share a common home directory with your local machine. Note 
that authorization information transmitted “in the clear” through a network hie 
system or using ftp or rep can be “stolen” by a network eavesdropper, and as 
such may enable unauthorized access. In many environments this level of security 
is not a concern, but if it is, you should know the exact semantics of the particular 
authorization data to know if this is actually a problem. 

Geometry Specifications 

One of the advantages of using window systems instead of hardwired terminals 
is that applications don’t have to be restricted to a particular size or location 
on the screen. Although the layout of windows on a display is controlled by the 
window manager that the user is running (described below), most X programs 
accept a command line argument of the form: 

-geometry widthxheight+xojf+yojf 

(where width, height, xojf, and yojf are numbers) for specifying a preferred size 
and location for this application’s main window. 
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The width and height parts of the geometry specihcation are usually measured 
in either pixels or characters, depending on the application. The xojf and yojf 
parts are measured in pixels and are used to specify the distance of the window 
from the left (or right) and top (or bottom) edges of the screen, respectively. 
Both types of offsets are measured from the indicated edge of the screen to the 
corresponding edge of the window. The X offset may be specihed in the following 
ways: 

+ xojf The left edge of the window is to be placed xoff pixels in from the left 
edge of the screen (i.e., the X coordinate of the window’s origin will be 
xojf ). xojf may be negative, in which case the window’s left edge will 
be off the screen. 

— xojf The right edge of the window is to be placed xojf pixels in from the right 

edge of the screen, xojf may be negative, in which case the window’s 
right edge will be off the screen. 

The Y offset has similar meanings: 

-\-yojf The top edge of the window is to be yoff pixels below the top edge of 
the screen (i.e. the Y coordinate of the window’s origin will be yoff ). 
yoff may be negative, in which case the window’s top edge will be off 
the screen. 

— yojf The bottom edge of the window is to be yojf pixels above the bottom 

edge of the screen, yojf may be negative, in which case the window’s 
bottom edge will be off the screen. 


Offsets must be given as pairs; in other words, in order to specify either xojf or 
yojf both must be present. Windows can be placed in the four corners of the 
screen using the following specihcations: 


■ + 0+0 
■ - 0+0 
■ - 0-0 
■ + 0-0 


(the upper left-hand corner) 
(the upper right-hand corner) 
(the lower right-hand corner) 
(the lower left-hand corner) 
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In the following examples, a terminal emulator will be placed in roughly the center 
of the screen and a load average monitor, mailbox, and clock will be placed in 
the upper right hand corner: 

xterm -fn 6x10 -geometry 80x24+30+200 & 
xclock -geometry 48x48-0+0 & 
xload -geometry 48x48-96+0 & 
xbiff -geometry 48x48-48+0 & 


Window Managers 

The layout of windows on the screen is controlled by special programs called 
window managers. Although many window managers will honor geometry 
specihcations as given, others may choose to ignore them (requiring the user to 
explicitly draw the window’s region on the screen with the pointer, for example). 

Since window managers are regular (albeit complex) client programs, a variety 
of different user interfaces can be built. The Hewlett-Packard distribution comes 
with window managers named mwm and dtwm, which support overlapping windows, 
popup menus, point-and-click or click-to-type input models, title bars, nice icons 
(and an icon manager for those who don’t like separate icon windows). 

See the user-contributed software in the MIT distribution for other popular 
window managers. 

Font Names 

Collections of characters for displaying text and symbols in X are known as 
fonts. A font typically contains images that share a common appearance and 
look nice together (for example, a single size, boldness, slantedness, and character 
set). Similarly, collections of fonts that are based on a common type face—the 
variations are usually called roman, bold, italic (or oblique), and bold italic (or 
bold oblique)—are called families. 

Fonts come in various sizes. The X server supports scalable fonts, meaning it is 
possible to create a font of arbitrary size from a single source for the font. The 
server supports scaling from outline fonts and bitmap fonts. Scaling from outline 
fonts usually produces signihcantly better results on large point sizes than scaling 
from bitmap fonts. 
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An X server can obtain fonts from individual files stored in directories in the 
file system, or from one or more font servers, or from a mixtures of directories 
and font servers. The list of places the server looks when trying to hnd a font is 
controlled by its font path. Although most installations will choose to have the 
server start up with all of the commonly used font directories in the font path, 
the font path can be changed at any time with the xset program. However, it 
is important to remember that the directory names are on the server’s machine, 
not on the application’s. Usually, fonts used by X servers and font servers can be 
found in subdirectories under /usr/lib/Xl 1/fonts: 

■ /usr/lib/Xll/fonts/iso_8859.l/75dpi 

This directory contains bitmap fonts contributed by Adobe Systems, Inc., 
Digital Equipment Corporation, Bitstream, Inc., Bigelow and Holmes, and 
Sun Microsystems, Inc. for 75 dot-per-inch displays. An integrated selection 
of sizes, styles, and weights are provided for each family. 

■ /usr/lib/Xl1/fonts/iso_8859.1/100dpi 

This directory contains 100 dot-per-inch versions of some of the fonts in the 
75dpi directory. 

Bitmap font hies are usually created by compiling a textual font description 
into binary form, using bdftopcf. Font databases are created by running the 
mkf ontdir program in the directory containing the source or compiled versions 
of the fonts. Whenever fonts are added to a directory, mkf ontdir should be rerun 
so that the server can hnd the new fonts. To make the server reread the font 
database, reset the font path with the xset program. For example, to add a font 
to a private directory, the following commands could be used: 

$ cp newfont.pcf "/myfonts 
$ mkfontdir "/myfonts 
$ xset fp rehash 

The xlsfonts program can be used to list the fonts available on a server. Font 
names tend to be fairly long, as they contain all of the information needed to 
uniquely identify individual fonts. However, the X server supports wildcarding 
of font names, so the full specihcation 

“-adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-l” 

might be abbreviated as 

“-*-courier-medium-r-normal--*-100-*-*-*-*-iso8859-l”. 
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Because the shell also has special meanings for and wildcarded font 
names should be quoted, as in: 

$ xlsfonts -fn ’-*-courier-medium-r-normal--*-100-*-*-*-*-*-*’ 

The xlsfonts program can be used to list all of the fonts that match a given 
pattern. With no arguments, it lists all available fonts. This will usually list the 
same font at many different sizes. To see just the base scalable font names, try 
using one of the following patterns: 

- 0 - 0 - 100 - 100 -*- 0 -*-* 

To convert one of the resulting names into a font at a specihc size, replace one 
of the hrst two zeros with a nonzero value. The held containing the hrst zero 
is for the pixel size; replace it with a specihc height in pixels to name a font at 
that size. Alternatively, the held containing the second zero is for the point size; 
replace it with a specihc size in decipoints (there are 722.7 decipoints to the inch) 
to name a font at that size. The last zero is an average width held, measured in 
tenths of pixels; some servers will anamorphically scale if this value is specihed. 

Font Server Names 

One of the following forms can be used to name a font server that accepts TCP 
connections: 

tcp/ hostname :port 

tcp/ hostname iportf cataloguelist 

The hostname specihes the name (or decimal numeric address) of the machine 
on which the font server is running. The port is the decimal TCP port on which 
the font server is listening for connections. The cataloguelist specihes a list of 
catalogue names, with “+” as a separator. For example: 

tcp/expo.Ics.mit.edu:7000 
tcp/18.30.0.212:7001/all. 
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Color Names 

Most applications provide ways of tailoring (usually through resources or 
command-line arguments) the colors of various elements in the text and graphics 
they display. A color can be specihed either by an abstract color name, or by a 
numerical color specihcation. The numerical specihcation can identify a color in 
either device-dependent (RGB) or device-independent terms. Color strings are 
case-insensitive. 

X supports the use of abstract color names, for example, “red”, “blue”. A value 
for this abstract name is obtained by searching one or more color-name databases. 
Xlib hrst searches zero or more client-side databases; the number, location, and 
content of these databases is implementation-dependent. If the name is not found, 
the color is looked up in the X server’s database. The text form of this database 
is commonly stored in the hie /usr/lib/Xll/rgb.txt. 

A numerical color specihcation consists of a color space name and a set of values 
in the following syntax: 

color_space_name : value j ... j value 

An RGB Device specihcation is identihed by the prehx “rgb:” and has the 
following syntax: 

rgb: red/green/blue 

where red, green, and blue are encoded as h, hh, hhh, or hhhh, and h represents 
a single hexadecimal digit. 

Note that h indicates the value scaled in 4 bits; hh, the value scaled in 8 bits; 
hhh, the value scaled in 12 bits; and hhhh the value scaled in 16 bits, respectively. 
These values are passed directly to the X server, and are assumed to be gamma 
corrected. 
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The eight primary colors can be represented as: 

■ Black: rgb:0/0/0 

■ Red: rgb:ffff/0/0 

■ Green: rgb:0/ffff/0 

■ Blue: rgb:0/0/ffff 

■ Yellow: rgb:ffff/ffff/O 

■ Magenta: rgb:ffff/0/ffff 

■ Cyan: rgb:0/ffff/ffff 

■ White: rgb:ffff/ffff/ffff 

For backward compatibility, an older syntax for RGB device is supported, but its 
continued use is not encouraged. The syntax is an initial “pound-sign” character, 
followed by a numeric specihcation, in one of the following formats: 

trgh (4 bits each) 

#rrggbb (8 bits each) 

#rrrgggbbb (12 bits each) 
trrrrggggbbbb (16 bits each) 

The r, g, and b represent single hexadecimal digits. When fewer than 16 bits 
each are specihed, they represent the most-signihcant bits of the value (unlike 
the “rgb:” syntax, in which values are scaled). For example, #3a7 is the same 

as #3000a0007000. 

An RGB intensity specihcation is identihed by the prehx “rgbi:” and has the 
following syntax: 

rgbi: red/green/blue 

The red, green, and blue are hoating-point values between 0.0 and 1.0, inclusive. 
They represent linear intensity values, with 1.0 indicating full intensity, 0.5 
indicating half intensity, and so on. These values will be gamma-corrected by 
Xlib before being sent to the X server. The input format for these values is an 
optional sign, a string of numbers possibly containing a decimal point, and an 
optional exponent held containing an “E” or “e” followed by a possibly signed 
integer string. 
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The standard device-independent string specifications have the following syntax: 

CIYJXZ: X! Y! Z (none, 1, none) 

CIEuvY: w/n/T (~.6, ~.6, 1) 

CIExyY:a;/?//T (^.75, ^.85, 1) 

CIELab:ii/a/5 (100, none, none) 

CIELuv: T/w/n (100, none, none) 

TekHVCriY/F/C (360, 100, 100) 

All of the values (C, H, V, A, T, Z, a, b, u, v, y, x) are floating-point values. 
Some of the values are constrained to be between zero and some upper bound; 
the upper bounds are given in parentheses above. The syntax for these values 
is an optional “+” or sign, a string of digits possibly containing a decimal 
point, and an optional exponent field consisting of an “E” or “e” followed by an 
optional “+” or “-’’sign, followed by a string of digits. 

For more information on device independent color, see the Xlib reference manual. 
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Keyboards 

The X keyboard model is broken into two layers: server-specific codes (called 
keycodes) which represent the physical keys, and server-independent symbols 
(called keysyms) which represent the letters or words that appear on the keys. 
Two tables are kept in the server for converting keycodes to keysyms: 

Modifier List Some keys (such as Shift, Control, and Caps Lock) are known 
as modifiers and are used to select different symbols that are 
attached to a single key (such as Shift-a, which generates a 
capital “A”, and Control-1, which generates a control character 
“~L”). The server keeps a list of keycodes corresponding to the 
various modifier keys. Whenever a key is pressed or released, 
the server generates an event that contains the keycode of the 
indicated key as well as a mask that specifies which of the 
modifier keys are currently pressed. Most servers set up this 
list to initially contain the various shift, control, and shift-lock 
keys on the keyboard. 

Keymap Table Applications translate event keycodes and modifier masks into 
keysyms using a keysym table which contains one row for each 
keycode and one column for various modifier states. This table 
is initialized by the server to correspond to normal typewriter 
conventions. The exact semantics of how the table is interpreted 
to produce keysyms depends on the particular program, libraries, 
and language input method used, but the following conventions 
for the first four keysyms in each row are generally adhered to. 

The first four elements of the list are split into two groups of 
keysyms. Group 1 contains the first and second keysyms; Group 
2 contains the third and fourth keysyms. Within each group, if 
the first element is alphabetic and the the second element is the 
special keysym NoSymbol, then the group is treated as equivalent 
to a group in which the first element is the lowercase letter and 
the second element is the uppercase letter. 

Switching between groups is controlled by the keysym named “Mode Switch”, 
by attaching that keysym to some key and attaching that key to any one of the 
modifiers Modi through Mod5. This modifier is called the group modifier. Group 
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1 is used when the group modiher is off, and Group 2 is used when the group 
modiher is on. 

Within a group, the modiher state determines which keysym to use. The hrst 
keysym is used when the Shift and Lock modihers are off. The second keysym 
is used when the Shift modiher is on, when the Lock modiher is on and the 
second keysym is uppercase alphabetic, or when the Lock modiher is on and 
is interpreted as ShiftLock. Otherwise, when the Lock modiher is on and is 
interpreted as CapsLock, the state of the Shift modiher is applied hrst to select 
a keysym; but if that keysym is lowercase alphabetic, then the corresponding 
uppercase keysym is used instead. 


Options 

Most X programs attempt to use the same names for command line options and 
arguments. All applications written with the X Toolkit Intrinsics automatically 
accept the following options: 

-display display This option specihes the name of the X server to use. 

-geometry geometry This option specihes the initial size and location of the 

window. 


-bg color, -background Either option specihes the color to use for the window 
color background. 


-bd color, Either option specihes the color to use for the window 

-bordercolor color border. 


-bw number. Either option specihes the width in pixels of the window 

-borderwidth number border. 


-fg color, -foreground Either option specihes the color to use for text or 
color graphics. 

-in font, -font font Either option specihes the font to use for displaying 

text. 


-iconic This option indicates that the user would prefer that 

the application’s windows initially not be visible as 
if the windows had be immediately iconihed by the 
user. Window managers may choose not to honor the 
application’s request. 
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-name 


-rv,-reverse 


+rv 

-selectionTimeout 

-synchronous 


-title string 

-xnllanguagelanguage 

[territory] [.codeset] 

-xrm resourcestring 


This option specifies the name under which resources for 
the application should be found. This option is useful 
in shell aliases to distinguish between invocations of an 
application, without resorting to creating links to alter 
the executable file name. 

Either option indicates that the program should sim¬ 
ulate reverse video if possible, often by swapping the 
foreground and background colors. Not all programs 
honor this or implement it correctly. It is usually only 
used on monochrome displays. 

This option indicates that the program should not 
simulate reverse video. This is used to override 
any defaults since reverse video doesn’t always work 
properly. 

This option specifies the timeout in milliseconds within 
which two communicating applications must respond to 
one another for a selection request. 

This option indicates that requests to the X server 
should be sent synchronously, instead of asynchronously. 
Since Xlib normally buffers requests to the server, er¬ 
rors do not necessarily get reported immediately after 
they occur. This option turns off the buffering so that 
the application can be debugged. It should never be 
used with a working program. 

This option specifies the title to be used for this window. 
This information is sometimes used by a window 
manager to provide some sort of header identifying the 
window. 

This option specifies the language, territory, and code¬ 
set for use in resolving resource and other filenames. 

This option specifies a resource name and value to 
override any defaults. It is also very useful for 
setting resources that don’t have explicit command line 
arguments. 
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Resources 


To make the tailoring of applications to personal preferences easier, X provides 
a mechanism for storing default values for program resources (e.g., background 
color, window title, etc.). Resources are specihed as strings that are read in from 
various places when an application is run. Program components are named in a 
hierarchical fashion, with each node in the hierarchy identihed by a class and an 
instance name. At the top level is the class and instance name of the application 
itself. By convention, the class name of the application is the same as the program 
name, but with the hrst letter capitalized, although some programs that begin 
with the letter “x” also capitalize the second letter for historical reasons. 


The precise syntax for resources is: 


ResourceLine 

Comment 

IncludeFile 

File Name 
ResourceSpec 

ResourceName 

Binding 

WhiteSpace 

Component 

ComponentName 

NameChar 

Value 


= Comment | IncludeFile | ResourceSpec | empty_line 
= “!” {any_character_except_null_or_newUne} 

— WhiteSpace “include” WhiteSpace FileName WhiteS¬ 
pace 

= valid filename for operating system 

= WhiteSpace ResourceName WhiteSpace WhiteSpace 
Value 

= [Binding] {Component Binding} ComponentName 

_ ii ?? I 

= {space I horizontal tab} 

= “?” I ComponentName 
= NameChar {NameChar} 

= “a”-“z” I “A”-“Z” I “0”-“9” I “ ” I 
= {any character except null or unescaped newline} 


Elements separated by vertical bar (“I”) are alternatives. Braces (“{” ... “}”) 
indicate zero or more repetitions of the enclosed elements. Brackets (“ [” ... “] ”) 
indicate that the enclosed element is optional. Quotes (" ... ") are used around 
literal characters. 


IncludeFile lines are interpreted by replacing the line with the contents of the 
specihed hie. The word “include” must be in lowercase. The hlename is 
interpreted relative to the directory of the hie in which the line occurs (for 
example, if the hlename contains no directory or contains a relative directory 
specihcation). 
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If a ResourceName contains a contiguous sequence of two or more Binding 
characters, the sequence will be replaced with single “ . ” character if the sequence 
contains only “. ” characters, otherwise the sequence will be replaced with a single 
character. 

A resource database never contains more than one entry for a given Resource- 
Name. If a resource hie contains multiple lines with the same ResourceName, the 
last line in the hie is used. 

Any whitespace character before or after the name or colon in a ResourceSpec 
are ignored. To allow a Value to begin with whitespace, the two-character 
sequence “space” (backslash followed by space) is recognized and replaced by 
a space character, and the two-character sequence “\tab” (backslash followed 
by horizontal tab) is recognized and replaced by a horizontal tab character. To 
allow a Value to contain embedded newline characters, the two-character sequence 
“n” is recognized and replaced by a newline character. To allow a Value to be 
broken across multiple lines in a text hie, the two-character sequence “\newline” 
(backslash followed by newline) is recognized and removed from the value. To 
allow a Value to contain arbitrary character codes, the four-character sequence 
“nnn”, where each n is a digit character in the range of 0-7, is recognized and 
replaced with a single byte that contains the octal value specihed by the sequence. 
Finally, the two-character sequence “\” is recognized and replaced with a single 
backslash. 

When an application looks for the value of a resource, it specihes a complete 
path in the hierarchy, with both class and instance names. However, resource 
values are usually given with only partially specihed names and classes, using 
pattern matching constructs. An asterisk (“*”) is a loose binding and is used to 
represent any number of intervening components, including none. A period (“ .”) 
is a tight binding and is used to separate immediately adjacent components. A 
question mark (“?”) is used to match any single component name or class. A 
database entry cannot end in a loose binding; the hnal component (which cannot 
be “?”) must be specihed. The lookup algorithm searches the resource database 
for the entry that most closely matches (is most specihc for) the full name and 
class being queried. When more than one database entry matches the full name 
and class, precedence rules are used to select just one. The full name and class 
are scanned from left to right (from highest level in the hierarchy to lowest), 
one component at a time. At each level, the corresponding component and/or 
binding of each matching entry is determined, and these matching components 
and bindings are compared according to precedence rules. Each of the rules is 

Reference Pages A-19 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


X Windows 


applied at each level, before moving to the next level, until a rule selects a single 
entry over all others. 

The rules (in order of precedence) are: 

1. An entry that contains a matching component (whether name, class, or “?”) 
takes precedence over entries that elide the level (that is, entries that match 
the level in a loose binding). 

2. An entry with a matching name takes precedence over both entries with a 
matching class and entries that match using “?”. An entry with a matching 
class takes precedence over entries that match using “?”. 

3. An entry preceded by a tight binding takes precedence over entries preceded 
by a loose binding. 

Programs based on the X Tookit Intrinsics obtain resources from the following 
sources (other programs usually support some subset of these sources): 

■ RESOURCE_MAIAGER root window property 

Any global resources that should be available to clients on all machines should 
be stored in the RESOURCE_MAIAGER property on the root window of the hrst 
screen using the xrdb program. This is frequently taken care of when the user 
starts X through the display manager. 

■ SCREEN_RESOURCES root window property 

Any resources specihc to a given screen (e.g. colors) that should be available 
to clients on all machines should be stored in the SCREEN_RESOURCES property 
on the root window of that screen. The xrdb program will sort resources 
automatically and place them in RESOURCE_MANAGER or SCREEN_RESOURCES, as 
appropriate. 

■ application-specihc hies 

Directories named by the environment variable XUSERFILESEARCHPATH or the 
environment variable XAPPLRESDIR, plus directories in a standard place (usually 
under /usr/lib/Xll, but this can be overridden with the XFILESEARCHPATH 
environment variable) are searched for for application-specihc resources. For 
example, application default resources are usually kept in /usr/lib/Xll/app- 
defaults. See the X Toolkit Intrinsics - C Language Interface manual for 
details. 

■ XEIVIROIMEIT 

Any user- and machine-specihc resources may be specihed by setting the 
XENVIRONMENT environment variable to the name of a resource hie to be 
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loaded by all applications. If this variable is not defined, a file named 
“$HOME/.Xdefaults -hostname” is looked for instead, where hostname is the 
name of the host where the application is executing. 

■ -xrm resourcestring 

Resources can also be specihed from the command line. The resourcestring is a 
single resource name and value as shown above. Note that if the string contains 
characters interpreted by the shell (e.g., asterisk), they must be quoted. Any 
number of -xrm arguments may be given on the command line. 

Program resources are organized into groups called classes, so that collections of 
individual resources (each of which are called instances) can be set all at once. 
By convention, the instance name of a resource begins with a lowercase letter and 
class name with an uppercase letter. Multiple word resources are concatenated 
with the hrst letter of the succeeding words capitalized. Applications written 
with the X Toolkit Intrinsics will have at least the following resources: 

■ background (class Background) 

This resource specihes the color to use for the window background. 

■ borderWidth (class BorderWidth) 

This resource specihes the width in pixels of the window border. 

■ borderColor (class BorderColor) 

This resource specihes the color to use for the window border. 

Most applications using the X Toolkit Intrinsics also have the resource fore¬ 
ground (class Foreground), specifying the color to use for text and graphics 
within the window. 
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By combining class and instance specifications, application preferences can be set 
quickly and easily. Users of color displays will frequently want to set Background 
and Foreground classes to particular defaults. Specific color instances such as 
text cursors can then be overridden without having to define all of the related 
resources. For example, 


dticon*Dashed: 
XTerm*cursorColor: 
XTerm*multiScroll: 
XTerm*jumpScroll: 
XTerm*reverseWrap: 
XTerm*curses: 

XTerm*Font: 

XTerm*scrollBar: 
XTerm*scrollbar*thickness: 
XTerm*multiClickTime: 
XTerm*charClass: 
XTerm*cutNewline: 
XTerm*cutToBeginningOfLine: 
XTerm*titeInhibit: 
XTerm*ttyModes: 
XLoad*Background: 
XLoad*Foreground: 
XLoad*highlight: 
XLoad*borderWidth: 
hpterm*Geometry: 
hpterm*Background: 
hpterm*Foreground: 
hpterm*Cursor: 
hpterm*BorderColor: 
hpterm*Font: 


off 

gold 

on 

on 

on 

on 

6x10 

on 

5 

500 

33:48,37:48,45-47:48,64:48 

off 

off 

on 

intr erase kill ~u 
gold 
red 
black 
0 

80x65-0-0 

rgb:5b/76/86 

white 

white 

white 

6x10 


If these resources were stored in a file called .Xdefaults in your home directory, 
they could be added to any existing resources in the server with the following 
command: 


$ xrdb -merge $H0ME/.Xdefaults 

This is frequently how user-friendly startup scripts merge user-specific defaults 
into any site-wide defaults. All sites are encouraged to set up convenient ways of 
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automatically loading resources. See the Xlib manual section “Resource Manager 
Functions” for more information. 

Examples 

The following is a collection of sample command lines for some of the more 
frequently used commands. For more information on a particular command, 
please refer to that command’s manual page. 

$ xrdb $HOME/.Xdefaults 

$ xmodmap -e "keysym Backspace = Delete" 

$ mkfontdir /usr/local/lib/Xll/otherfonts 
$ xset fp+ /usr/local/lib/Xll/otherfonts 
$ xmodmap $H0ME/.keymap.km 
$ xsetroot -solid ’rgbi:.8/.8/.8’ 

$ xset b 100 400 c 50 s 1800 r on 
$ xset q 
$ mwm 

$ xclock -geometry 48x48-0+0 -bg blue -fg white 
$ xlsfonts ’*helvetica*’ 

$ xwininfo -root 
$ xhost -joesworkstation 
$ xwd I xwud 

$ xterm -geometry 80x66-0-0 -name myxterm $* 

Diagnostics 

A wide variety of error messages are generated from various programs. The 
default error handler in Xlib (also used by many toolkits) uses standard resources 
to construct diagnostic messages when errors occur. The defaults for these 
messages are usually stored in /usr/lib/Xll/XErrorDB. If this hie is not present, 
error messages will be rather terse and cryptic. 

When the X Toolkit Intrinsics encounter errors converting resource strings to 
the appropriate internal format, no error messages are usually printed. This is 
convenient when it is desirable to have one set of resources across a variety of 
displays (e.g. color vs. monochrome, lots of fonts vs. very few, etc.), although it 
can pose problems for trying to determine why an application might be failing. 
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This behavior can be overridden by the setting the StringConversionsWarning 
resource. 

To force the X Toolkit Intrinsics to always print string conversion error messages, 
the following resource should be placed in the .Xdefaults hie in the user’s home 
directory. This hie is then loaded into the RESOURCE_MAIAGER property using the 
xrdb program: 

*StringConversionWarnings: on 

To have conversion messages printed for just a particular application, the 
appropriate instance name can be placed before the asterisk: 

xterm*StringConversionWarnings: on 


See Also 

bdftopcf(l), bitmap(l), fs(l), hpterm(l) mkfontdir(l), mwm(l), xauth(l), 
xclock(l), xcmsdb(l), xfd(l), xhost(l), xinitcolor(l), xload(l), xlsfonts(l), 
xmodmap(l), xpr(l), xprop(l), xrdb(l), xrefresh(l), xset(l), xsetroot(l), 
xterm(l), xwd(l), xwininfo(l), xwud(l), Xserver(l), Xlib - C Language X 
Interface, and X Toolkit Intrinsics - C Language Interface. 


Copyright 

The following copyright and permission notice outlines the rights and restrictions 
covering most parts of the core distribution of the X Window System from 
MIT. Other parts have additional or different copyrights and permissions; see 
the individual source hies. 

Copyright 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991 by the Massachusetts 
Institute of Technology. 

Permission to use, copy, modify, distribute, and sell this software and its 
documentation for any purpose is hereby granted without fee, provided that the 
above copyright notice appear in all copies and that both that copyright 
notice and this permission notice appear in supporting documentation, and that 
the name of MIT not be used in advertising or publicity pertaining to 
distribution of the software without specific, written prior permission. MIT 
makes no representations about the suitability of this software for any 
purpose. It is provided "as is" without express or implied warranty. 
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Trademarks 

X Window System is a trademark of MIT. 

Authors 

A cast of thousands, literally. The MIT Release 5 distribution is brought to you 
by the MIT X Consortium. The names of all people who made it a reality will be 
found in the individual documents and source hies. The staff members at MIT 
responsible for this release are: Donna Converse (MIT X Consortium), Stephen 
Gildea (MIT X Consortium), Susan Hardy (MIT X Consortium), Jay Hersh (MIT 
X Consortium), Keith Packard (MIT X Consortium), David Sternlicht (MIT X 
Consortium), Bob Scheiher (MIT X Consortium), and Ralph Swick (Digital/MIT 
Project Athena). 


A 
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Synopsis 

X : displaynumber [-option] ttyname 


Description 

“X” is the generic name for the window system server. It is started by the 
dtlogin(lX) program which is typically run by init(lM). Alternatively it may 
be started from the xinit(l) program, which is called by xllstart. The 
displaynumber argument is used by clients in their DISPLAY environment variables 
to indicate which server to contact (machines may have several displays attached). 
This number can be any number. If no number is specihed, 0 is used. This number 
is also used in determining the names of various startup hies. The ttyname 
argument is passed in by init and isn’t used. 

The Hewlett-Packard server has support for the following protocols: 

TCP/IP The server listens on port 6000-|-n, where n is the display 

number. 

Local Socket IPC The hie name for the socket is 

Mechanism “/usr/spool/sockets/Xll/*” where is the display 

number. 


Shared Memory IPC This is the default connection that the X Library will 

use to connect to an X server on the same machine if 
the DISPLAY environment variable is set to “local: *” or 
“: *” where is the number of the display. 


When the server starts up, it takes over the display. If you are running on a 
workstation whose console is the display, you cannot log into the console while 
the server is running. 
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Options 

The following options can be given on the command line to the X server. 

-a number Sets pointer acceleration (i.e. the ratio of how much 

is reported to how much the user actually moved the 
pointer). 

-audit level Sets the audit trail level. The default level is 1, 

meaning only connection rejections are reported. Level 
2 additionally reports all successful connections and 
disconnects. Level 0 turns off the audit trail. Audit 
lines are sent as standard error output. 

-auth authorization-file Specihes a hie which contains a collection of authoriza¬ 
tion records used to authenticate access. 


be 


-bs 

-c 

c volume 
-CO filename 


Disables certain kinds of error checking, for bug com¬ 
patibility with previous releases (e.g., to work around 
bugs in R2 and R3 xterms and toolkits). Deprecated. 

Disables backing store support on all screens. 

Turns off key-click. 

Sets key-click volume (allowable range: 0-100). 

Sets name of RGB color database. 


-core 


Causes the server to generate a core dump on fatal 
errors. 


-dpi resolution 


-f volume 
-fc cursorFont 
-fn font 
-fp fontPath 


Sets the resolution of the screen, in dots per inch. To 
be used when the server cannot determine the screen 
size from the hardware. 

Sets beep (bell) volume (allowable range: 0-100). 

Sets default cursor font. 

Sets the default font. 

Sets the search path for fonts. This path is a comma- 
separated list of directories which the server searches 
for font databases. 
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-help 

-I 


-logo 


nologo 


-p minutes 

-pn 


-pn 


-r 

r 

-s minutes 


Prints a usage message. 

Causes all remaining command line arguments to be 
ignored. 

Turns on the X Window System logo display in the 
screen-saver. There is currently no way to change this 
from a client. 

Turns off the X Window System logo display in the 
screen-saver. There is currently no way to change this 
from a client. 

Sets screen-saver pattern cycle time in minutes. 

Allows X server to run even if one or more communica¬ 
tions mechanisms fails to initialize. 

Permits the server to continue running if it fails to 
establish all of its well-known sockets, but establishes 
at least one. 

Turns off keyboard auto-repeat. 

Turns on keyboard auto-repeat. 

Sets screen-saver timeout time in minutes. 


-su 

-t number 

-terminate 

-to seconds 

-tst 

ttyxx 

-terminate 


Disables save under support on all screens. 

Sets pointer acceleration threshold in pixels (i.e. af¬ 
ter how many pixels pointer acceleration should take 
effect). 

Causes the server to terminate at server reset, instead 
of continuing to run. 

Sets default connection timeout in seconds. 

Disables all testing extensions (e.g., XTEST, XTrap, 
XTestExtensionl). 

Ignored; for servers started the ancient way (from 

init). 

Causes server to terminate when all clients disconnect. 
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V Sets video-on screen-saver preference. A window that 

changes regularly will be used to save the screen. 

-V Sets video-off screen-saver preference. The screen will 

be blanked to save the screen. 

-wm Forces the default backing-store of all windows to be 

WhenMapped; a less-expensive way of getting backing- 
store to apply to all windows. 

You can also have the X server connect to xdm(l) or dtlogin(lX) using XDMCP. 

Although this is not typically useful as it doesn’t allow xdm to manage the server 

process, it can be used to debug XDMCP implementations, and serves as a sample 

implementation of the server side of XDMCP. The following options control the 

behavior of XDMCP: 

-query host-name Enable XDMCP and send Query packets to the speci- 

hed host. 

Enable XDMCP and broadcast BroadcastQuery pack¬ 
ets to the network. The hrst responding display man¬ 
ager will be chosen for the session. 

Enable XDMCP and send IndirectQuery packets to the 
specihed host. 

-port port-num Use an alternate port number for XDMCP packets. 

Must be specihed before any -query, -broadcast or 
-indirect options. Default port number is 177. 

-class display-class XDMCP has an additional display qualiher used in 

resource lookup for display-specihc options. This option 
sets that value, by default it is “MIT-Unspecihed” (not 
a very useful value). 

-cookie xdm-auth-bits When testing XDM-AUTHEITICATIOI-1, a private key 

is shared between the server and the manager. This 
option sets the value of that private data (not that it’s 
very private, being on the command line and all ... ). 

-displaylD display-id Yet another XDMCP-specihc value, this one allows the 

display manager to identify each display so that it can 
locate the shared key. 
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Running From init 

Though X will usually be run by dtlogin from init, it is possible to run X 
directly from init. For information about running X from dtlogin, see the 
dtlogin man page. 

To run X directly from init, it is necessary to modify /etc/inittab and 
/etc/gettydef s. Detailed information on these hies may be obtained from the 
inittab(4) and gettydefs(4) man pages. 

To run X from init on display 0, with a login xterm running on /dev/ttypf, in 
init state 3, the following line must be added to /etc/inittab: 

XO:3:respawn:env PATH=/bin:/usr/bin/Xll:/usr/bin xinit -L ttyqf -- :0 

To run X with a login hpterm, the following should be used instead: 

XO:3:respawn:env PATH=/bin:/usr/bin/Xll:/usr/bin xinit hpterm =+1+1 \ 

-n login -L ttyqf -- :0 

In addition, the following line must be added to /etc/gettydef s (this should be 
a single line): 

XwindoH# B9600 HUPCL PAREIB CS7 # B9600 SAIE PAREIB CS7 ISTRIP IXAIY \ 

TAB3 #X login: #Xwindow 

There should not be a getty running against the display whenever X is run from 

xinit. 

Security 

The sample server implements a simplistic authorization protocol, MIT-MAGIC- 
COOKIE-1 which uses data private to authorized clients and the server. This 
is a rather trivial scheme; if the client passes authorization data which is the 
same as the server has, it is allowed access. This scheme is inferior to host-based 
access control mechanisms in environments with unsecure networks as it allows 
any host to connect, given that it has discovered the private key. But in many 
environments, this level of security is better than the host-based scheme as it 
allows access control per-user instead of per-host. 

In addition, the server provides support for a DES-based authorization scheme, 
XDM-AUTHORIZATION-1, which is more secure (given a secure key-distribution 
mechanism), but as DES is not generally distributable, the implementation 
is missing routines to encrypt and decrypt the authorization data. This 
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authorization scheme can be used in conjunction with XDMCP’s authentication 
scheme, XDM-AUTHEITICATIOI-1 or in isolation. 

The authorization data is passed to the server in a private hie named with the 
-auth command line option. Each time the server is about to accept the hrst 
connection after a reset (or when the server is starting), it reads this hie. If 
this hie contains any authorization records, the local host is not automatically 
allowed access to the server, and only clients which send one of the authorization 
records contained in the hie in the connection setup information will be allowed 
access. See the Xau manual page for a description of the binary format of this 
hie. Maintenance of this hie, and distribution of its contents to remote sites for 
use there, is left as an exercise for the reader. 

The sample server also uses a host-based access control list for deciding whether or 
not to accept connections from clients on a particular machine. This list initially 
consists of the host on which the server is running as well as any machines listed 
in the hie /etc/Xn.hosts, where n is the display number of the server. Each 
line of the hie should contain an Internet hostname (e.g., expo.lcs.mit.edu). 
There should be no leading or trailing spaces on any lines. Eor example: 

joesworkstation 
corporate.company.com 

Users can add or remove hosts from this list and enable or disable access control 
using the xhost command from the same machine as the server. Eor example: 

$ xhost Tjanesworkstation 

janesworkstation being added to access control list 
$ xhost + 

all hosts being allowed (access control disabled) 

$ xhost - 

all hosts being restricted (access control enabled) 

$ xhost 

access control enabled (only the following hosts are allowed) 

joesworkstation 

janesworkstation 

corporate.company.com 
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Signals 

The X server attaches special meaning to the following signals: 

SIGHUP This signal causes the server to close all existing connections, free all 
resources, and restore all defaults. It is sent by the display manager 
(xdm or dtlogin) whenever the main user’s main application exits to 
force the server to clean up and prepare for the next user. 

SIGTERM This signal causes the server to exit cleanly. 

SIGUSRl This signal is used quite differently from either of the above. When 
the server starts, it checks to see if it has inherited SIGUSRl as 
SIG_IGN instead of the usual SIG_DFL. In this case, the server 
sends a SIGUSRl to its parent process after it has set up the 
various connection schemes, xdm uses this feature to recognize when 
connecting to the server is possible. 

Fonts 

Fonts are usually stored as individual hies in directories. The list of directories in 
which the server looks when trying to open a font is controlled by the font path. 
Although most sites will choose to have the server start up with the appropriate 
font path (using the -fp option mentioned above), it can be overridden using the 
xset program. 

Font databases are created by running the mkfontdir or stmkdirs program in 
the directory containing the compiled versions of the fonts (mkfontdir) or font 
outlines (stmkdirs.) Whenever fonts are added to a directory, mkfontdir or 
stmkdirs should be rerun so that the server can hud the new fonts. If mkfontdir 
or stmkdirs is not run, the server will not be able to hud any of the new fonts 
in the directory. 
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In addition, the X server supports font servers. A font server is a networked 
program that supplies fonts to X servers and other capable programs. In order 
to communicate with a font server, the font servers address must be supplied as 
part of the X server’s font path. A font server’s address is specihed as: 

transport/hostname '.port-number 

where transport is always “tcp”, hostname is the hostname of the machine being 
connected to (no hostname means a local connection) and port-number is the tcp 
address that the font server is listening at (typically 7000.) 

Diagnostics 

Too numerous to list them all. If run from init(lM), errors are logged in the hie 

/usr/adm/X*msgs. 


A 
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Files 


/etc/inittab 
/etc/gettydefs 
/etc/X*.hosts 
/usr/lib/Xll/fonts 
/usr/lib/Xll/rgb.txt 
/usr/lib/Xll/rgb.pag 
/usr/lib/Xll/rgb.dir 
/usr/spool/sockets/X11/* 
/usr/adm/X*msgs 
/usr/lib/Xll/X*devices 

/usr/lib/Xll/X*screens 

/usr/Iib/Xll/X*pointerkeys 

/usr/lib/Xll/XHPkeymaps 


Script for the init process 

Speed and terminal settings used by getty 

Initial access control list 

Top level font directory 

Color database 

Color database 

Color database 

IPC mechanism socket 

Error log hie 

Input devices used by the server. This hie 
contains many example conhgurations. 

Screens used by the server. This hie contains 
many example conhgurations. 

Keyboard pointer device hie. This hie contains 
many example conhgurations. 

Key device database used by the X server. 


Notes 

The option syntax is inconsistent with itself and xset(l). The acceleration option 
should take a numerator and a denominator like the protocol. The color database 
is missing a large number of colors. However, there doesn’t seem to be a better 
one available that can generate RGB values. 



Copyright 

Copyright 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1992 Massachusetts 
Institute of Technology. 

Copyright 1992 Hewlett Packard Company. 

See X(l) for a full statement of rights and permissions. 
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Origin 

MIT Distribution. 

See Also 

dtlogin(lX), bdftopcf(1), fs(l), getty(lM), gettydefs(4), gwindstop(l), 
hpterm(l), init(lM), inittab(4), mkfontdir(l), rgb(l), stmkdirs(l), 
xllstart(l), xclock(l), xfd(l), xhost(l), xinit(l), xinitcolormap(l), 
xload(l), xmodmap(l), xrefresh(l), xseethru(l), xset(l), xsetroot(l), 
xterm(l), xwcreate(l), xwd(l), xwdestroy(l), xwininfo(l), xwud(l). 


Reference Pages A-35 


FINAL TRIM SIZE : 7.5 in x 9.0 in 


FINAL TRIM SIZE : 7.5 in x 9.0 in 



Index 



Index 


3 

3BitCenterColor, 3-10 

B 

BufferSwapsonVerticalBlank, 3-3 
buttons 

actions, 5-13 
changing mappings, 5-14 
cording, 5-20 
mappings, 5-14 
mouse, 5-13, 5-17 
operation functions, 5-18 

C 

CenterColor, 3-10 
chording, 5-20 
colormap, 5-12 
ColormapManagement, 3-19 
ColormapsandColormapManagement, 
3-19 

ColorRecovery, 3-7 
Compiling 
HP PEX, 2-10 
HP-PHIGS, 2-4 
OpenGL, 2-11 
Starbase, 2-2 
configuration 
special, 5-1 
Configurations 
XServer, 3-14 
CRX, 3-23 
CRX24Z, 3-24 
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default 
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Libraries, 2-6 
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Device, 3-11 
Xscreens, 3-2 
EreedomSeriestm, 3-37 


Index-1 


EINAL TRIM SIZE : 7.5 in x 9.0 in 


Index 



G 

GLX, 3-37 

GraphicsResourceManagerGRM, 3-8 
GRMGraphicsResourceManager, 3-8 
GRX, 3-23 

H 
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host 

names, 5-2 

HPGolorRecovery, 3-7 
HP-HIL interface, 5-3 
HP PEX 

Gompiling, 2-10 
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Gompiling, 2-4 
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I 

ImageTextViaBitMap, 3-10 
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K 

key 

bindings, 5-24 
map, 5-28 
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keyboard, 5-17 
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Libraries 

Devicedriver, 2-6 
Loading 
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loopback address, 5-2 

M 

mapping 

mouse buttons, 5-14 
MBX, 3-4 
modifier 

key bindings, 5-24 
keys, 5-21 
modifying 

XOpointerkeys, 5-16 
mouse 

button, 5-14 
button mappings, 5-14 
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keys, 5-20 
without, 5-15 
mouseless operation, 5-16 
MultiDisplaySupport, 3-16 
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OpenGL 
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movement functions, 5-17 
specifying keys, 5-22 
printing 

key map, 5-28 

R 

remapping, 5-24, 5-26 
reset functions, 5-19 
RS-232C interface, 5-3 

S 

screen 

default configuration file, 5-1 
SettingUnsettingEnvironment Variables, 
3-2 

SharedMemory, 3-8 
SingleLogicalScreenandHPVUE, 3-6 
SingleLogicalScreenSLS, 3-5 
SLSSingleLogicalScreen, 3-5, 3-6 
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SpecialDeviceEiles, 3-11 
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XConhgurations, 3-14 
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X keyboard devices, 5-3 
xmodmap client, 5-26, 5-27 
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X*pointerkeys hie, 5-12, 5-15, 5-16, 
5-17, 5-21 
X*screens hie, 5-1 
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X Toolkit warning, 5-12 
X Window System, 5-11 
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